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ABOUT THIS GUIDE 


We've designed this 8-08_6 Implementor's Guidf> 
to provide the information you need to know 
in order to generate various TurboDOS config¬ 
urations for 8086-family microcomputers, and 
to write the driver modules for various peri¬ 
pheral devices. This document describes the 
modular architecture and internal programming 
conventions of TurboDOS, and explains the 
procedures for system generation, serializa¬ 
tion, and distribution. It also provides 
detailed interface specifications for hard- 
ware-dependent driver modules, and includes 
assembler source listings of sample drivers. 


Assumptions In writing this guide, we've assumed that you 

are an OEM, dealer, or sophisticated TurboDOS 
user, knowledgable in 8086-family microcompu¬ 
ter hardware and assembly—language program¬ 
ming. We've also assumed you have read both 
the and the 8086 Frooram m er's 

and are therefore familiar with the 
commands, external features, and internal 
functions of 8086 TurboDOS. 


Organization This guide starts with a section that de¬ 

scribes the architecture of TurboDOS. It 
explains the function of each internal module 
of the operating system, and how these 
modules may be combined to create the various 
configurations of TurboDOS. 

The next section explains the system genera¬ 
tion procedure in detail, and describes each 
TurboDOS parameter which can be modified 
during system generation. 

The third section of this guide explains the 
TurboDOS distribution procedure, including 
licensing, serialization, and support. 
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Organization The fourth section is devoted to an in-depth 

(Continued) discussion of internal programming conven¬ 

tions, aimed at the programmer writing 
drivers or resident processes for TurboDOS. 

The fifth section presents formal interface 
specifications for implementing hardware- 
dependent driver modules. 

This guide concludes with a large appendix 
containing assembler source listings of 
actual driver modules. The sample drivers 
cover a wide range of peripheral devices, and 
provide an excellent starting point for 
programmers involved in driver development. 


Related Documents In addition to this guide, you might be 

interested in four other related documents: 


Tuxb£>DQB lA. iISfiJLiS 

TurboDOS 1.4 8086 Pro qrammfij:J.S 

TurboDOS 1.4 z&Sl 


1 A »7Qn 


- ■ „ J ^ 


You should read the first two volumes before 
start into this document. The 
introduces the external features and facili¬ 
ties of TurboDOS, and describes each TurboDOS 
command. The ex¬ 

plains the internal workings of TurboDOS, and 
describes each operating system function in 
detail. 


You'll need the Z80 guides if you are pro¬ 
gramming or configuring a TurboDOS system 
that uses Z80 microprocessors. 
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ARCHITECTURE This section introduces you to the internal 

architecture of the TurboDOS operating sys¬ 
tem. TurboDOS is highly modular, consisting 
of more than forty separate functional 
modules distributed in relocatable form. 
These modules are "building blocks" that you 
can combine in various ways to produce a 
family of compatible operating systems. This 
section describes the modules in detail, and 
describes how to combine them in various 
configurations. 

Possible TurboDOS configurations include: 

. single-user without spooling 
. single-user with spooling 
. network master 

. simple network slave (no local disks) 

. complex network slave (with local disks) 

Numerous subtle variations are possible in 
each of these categories. 


Module Hierarchy The diagram on page 1-3 illustrates how the 

functional modules of TurboDOS interact. As 
the diagram shows, the architecture of Turbo¬ 
DOS can be viewed as a three-level hierarchy. 


Process Level The highest level of the hierarchy is the 

process level . TurboDOS can support many 
concurrent processes at this level. There is 
one active process that supports the local 
user who is executing commands and programs 
in the local TPA. There are also processes 
to support users running on other computers 
and making requests of the local computer 
over the network. There are processes to 
handle background printing (de-spooling) on 
local printers. Finally, there is a process 
that periodically causes disk buffers to be 
written out to disk. 
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Kernel Level The intermediate level of the hierarchy is 

the kernel lejV-el . The kernel supports the 
various C-functions and T-functions, and 
controls the sharing of computer resources 
such as processor time, memory, peripheral 
devices, and disk files. Processes make 
requests of the kernel through the entrypoint 
module OSNTRY, which decodes each C-function 
and T-function by number and invokes the 
appropriate kernel module. 


Driver Level The lowest level of the hierarchy is the 

driver level . and contains all the device¬ 
dependent drivers necessary to interface 
TurboDOS to the particular hardware being 
used. Drivers must be provided for all peri¬ 
pherals, including console, printers, disks, 
communications channels, and network inter¬ 
face. A driver is also required for the 
real-time clock (or other periodic interrupt 
source). 

TurboDOS is designed to interface with almost 
any kind of peripheral hardware. It operates 
most efficiently with interrupt-driven, DMA- 
type interfaces, but can also work fine using 
polled and programmed-I/0 devices. 


TurboDOS Loader The TurboDOS loader OSLOAD.CMD is a program 

containing an abbreviated version of the 
kernel and drivers. Its purpose is to load 
the full TurboDOS operating system from a 
disk file (OSMASTER.SYS) into memory at each 
system cold-start. 
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Process Modules i Module —I-Jlin gti-PR— -- 

j ' 

I LCLUSR Responsible for supporting local I 
I user's TPA activities. 

I 

1 LCLMSG Contains all 0/S error messages. 

1 ' 

1 LCLTBL Local user option table. j 

1 CMDINT Command interpreter, processes I 

I commands from local user. I 

I I 

I AUTLOD Autoload routine which processes I 

I COLDSTRT.AUT and WARMSTRT.AUT. 1 

I SGLUSR Flushes disk buffers at each I 

I console input. Use for single- I 

I user systems instead of FLUSHR. I 

I AUTLOG Automatic log-on routine. Used I 

I when full log-on security is not I 

1 desired. See AUTUSR patch point. I 

I • 

I BIOS Direct BIOS Call (C-fcn 50). I 

I SUBMIT Routine to emulate CP/M proces- I 

I sing of $$$.SUB files. I 

I NETSVC Services network requests from I 

I other processors on the network. 1 

1 • 

I NETTBL Tables to define local network 1 

I topology, used by NETSVC+NETREQ. I 

I NETFWD Manages network message forward- I 
I ing. Requires NETREQ+NETSVC. I 

I I 

I DSPOOL Processes background printing. I 

I _ ' 

I FLUSHR Periodically flushes disk buf- I 

I fers. Use for network master 1 

! configuration instead of SGLUSR. 1 

I 1 
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Kernel Modules 




UbiNTKI 


FILMGR 

FILSUP 

FILCOM 

FILLOK 

FFOMGR 

DRVLOK 

BUFMGR 

DSKMGR 

DSKTBL 

NONFIL 

CPMSUP 


Kernel entrypoint module which 
decodes each C-function and 
T-function by number and invokes 
the appropriate kernel module. 

File manager responsible for 
requests involving local files. 

File support routines used by 
FILMGR. 

Processes common file-oriented 
requests that are never sent 
over the network. 

File- and record-level interlock 
routines called by FILMGR. 

FIFO management routines called 
by FILLOK. 

Drive interlock routines. 

Buffer manager called by FILMGR. 
Maintains pool of disk buffers 
used to speed local file access. 

Disk manager responsible for 
physical access to local disks, 
called by BUFMGR. 

Table defining drives A-P as 
local or remote disk drives. 

Responsible for functions that 
are not file-oriented. 

Processes C-functions 7, 8, 24, 
28, 29, 31, 37 and 107 which are 
rarely used. May be omitted. 
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Kernel Modules 
(Continued) 


I Module _i 
I 

I MPMSUP 

I 

I 

1 QUEMGR 
1 
I 
I 

1 CONMGR 
I 

I CONTBL 
I 

I DOMGR 
I 

I INPLN 

I 

I 

I LSTMGR 
1 

I LSTTBL 
1 
I 

I SPOOLR 


COMMGR 

NETREQ 

MSGFMT 

NETMGR 


_ Function --j 

Processes C-functions 141-143, I 

153, 160, 161 (optional). j 

Emulates MP/M queues, supports I 

C-functions 134-140 (optional). I 
Requires MPMSUP. [ 

Responsible for console I/O. I 

Links CONMGR to console driver. I 

Responsible for do-files. I 

Console input line editor used I 

by CMDINT and C-function 10. I 

Responsible for printer output. I 

Table defining printers A-P and I 

queues A-P as local or remote. I 

Print spooler which diverts 1 

print output to a spool file I 

when spooling is activated. I 

Also handles direct printing to 1 
remote printers. • 

Responsible for communications I 
channel functions. I 

Responsible for issuing network I 
request messages for all func- I 
tions not processed locally. I 

Network message format table I 

used by NETREQ. j 

Network message routing routine 1 
used by NETSVC and NETREQ. I 
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Kernel Modules 
(Continued) 


■ Module . I_ 


NistLOD 

Loads programs over the network. 

RTCMGR 

Real-time clock manager keeps 
system date and time. 

DSPCHR 

Multi-task dispatcher which con¬ 
trols sharing of the local pro¬ 
cessor among multiple processes. 

DSPSGL 

Null dispatcher used as alterna¬ 
tive to DSPCHR when only one 
process is required (OSLOAD.CMD 
and single-user w/o spooling). 

MEMMGR 

Memory manager responsible for 
dynamic allocation of memory, 
and for supporting TPA alloca¬ 
tion C-functions (53-58). 

COMSUB 

Common subroutines used in all 
configurations. 

SYSNIT 

System initialization routine 
executed at system cold-start. 

RTCNUL 

Null real-time clock driver, 
used in configurations where 
there is no periodic interrupt 
source. 

CONREM 

Remote console driver for net¬ 
work master to support MASTER 
command. 

PATCH 

128 bytes of zeroes, may be in¬ 
cluded to provide patch area. 
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- - ■ - 



1 Pvnction - 


1 

1 

CONDR_ 

Console I/O driver. 


1 

1 

1 

LSTDR_ 

Printer output driver(s). 


1 

1 

DSKDR_ 

Disk driver(s). 


1 

1 

CKTDIL. 

Network circuit driver(s). 


1 

1 

1 

COMDRV 

Communications channel driver. 


1 

1 

RTCDRV 

Real-time clock driver. 


1 

1 

1 

MEMTBL 

Table defining the size and 
structure of main memory (RAM). 


1 

1 

1 

1 

HDWNIT 

Cold-start initialization for 
all hardware-dependent drivers. 







Standard Packages 


To simplify the system generation procesSf 
the most commonly-used combinations of Turbo¬ 
DOS modules are pre-packaged into the follow¬ 
ing standard configurations; 


I STDLOADR 
I STDSINGL 
I STDSPOOL 
1 STDMASTR 
I STDSLAVE 
I STDSLAVX 


cold-start loader 
single-user without spooling 
single-user with spooling 
network master 

simple slave w/o local disks 
complex slave with local disks 


The contents of each standard package is 
detailed in the matrix on the next page. 
Most TurboDOS requirements can be satisfied 
by linking the appropriate standard package 
together with a few additional modules plus 
the requisite driver modules. 
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Module 1 

Z _L 

LOADR 1 

SINGL J 

HASTR_ J. 


.SLAVX__ 

AUTLOD 

.2 


AUTLOD 

AUTLOD 

AUTLOD 

AUTLOD 

AUTLOD 

AUTLOG 

. 0 

- 

AUTLOG 

AUTLOG 

» r-ffTiT' 

JlLxKJKs 

n TTm-r r\^ 

±\U ±UKJ\J 

ATimr r\r^ 
nu xu\J\j 

BIOS 

.3 

- 

BIOS 

BIOS 

BIOS 

BIOS 

BIOS 

BUFMGR 

1.2 

BUFMGR 

BUFMGR 

BUFMGR 

BUFMGR 

- 

BUFMGR 

CMDINT 

1.7 

- 

CMDINT 

CMDINT 

CMDINT 

CMDINT 

CMDINT 

COMMGR 

.1 

- 

COMMGR 

COMMGR 

COMMGR 

COMMGR 

COMMGR 

COMSUB 

.2 

COMSUB 

COMSUB 

COMSUB 

COMSUB 

COMSUB 

COMSUB 

CONMGR 

.4 

CONMGR 

CONMGR 

CONMGR 

CONMGR 

CONMGR 

CONMGR 

CONREM 

.5 

- 

- 

- 

+ 

— 

— 

CONTBL 

.0 

CONTBL 

CONTBL 

CONTBL 

CONTBL 

CONTBL 

CONTBL 

CPMSUP 

.3 

- 

+ 

+ 

+ 

+ 

+ 

DOMGR 

.4 

- 

DOMGR 

DOMGR 

DOMGR 

DOMGR 

DOMGR 

DRVLOK 

.1 

- 

- 

- 

DRVLOK 

- 

— 

DSKMGR 

.6 

DSKMGR 

DSKMGR 

DSKMGR 

DSKMGR 

— 

DSKMGR 

DSKTBL 

.0 

DSKTBL 

DSKTBL 

DSKTBL 

DSKTBL 

DSKTBL 

DSKTBL 

DSPCHR 

.7 

- 

- 

DSPCHR 

DSPCHR 

DSPCHR 

DSPCHR 

DSPOOL 

1.0 

- 

- 

DSPOOL 

DSPOOL 

— 

DSPOOL 

DSPSGL 

.2 

DSPSGL 

DSPSGL 

- 

— 

— 

— 

FFOMGR 

1.1 

- 

- 

- 

FFOMGR 

— 

— 

FILCOM 

.4 

FILCOM 

FILCOM 

FILCOM 

FILCOM 

FILCOM 

FILCOM 

FILLOK 

2.0 

- 

- 

- 

FILLOK 

- 

— 

FILMGR 

o c; 

FILMGR 

FILMGR 

FILMGR 

FILMGR 

— 

FILMGR 

FILSUP 

2.9 

FILSUP 

FILSUP 

FILSUP 

FILSUP 

- 

FILSUP 

FLUSHR 

.2 

- 

- 

- 

FLUSHR 

- 

— 

INPLN 

.2 

- 

INPLN 

INPLN 

INPLN 

INPLN 

INPLN 

LCLMSG 

.4 

- 

LCLMSG 

LCLMSG 

LCLMSG 

LCLMSG 

LCLMSG 

LCLTBL 

.0 

- 

LCLTBL 

LCLTBL 

LCLTBL 

LCLTBL 

LCLTBL 

LCLUSR 

1.1 

- 

LCLUSR 

LCLUSR 

LCLUSR 

LCLUSR 

LCLUSR 

LDRMSG 

.1 

LDRMSG 

- 

- 

- 

— 

— 

LSTMGR 

.3 

- 

LSTMGR 

LSTMGR 

LSTMGR 

LSTMGR 

LSTMGR 

LSTTBL 

.1 

- 

LSTTBL 

LSTTBL 

LSTTBL 

LSTTBL 

LSTTBL 

MEMMGR 

1.2 

- 

MEMMGR 

MEMMGR 

MEMMGR 

MEMMGR 

MEMMGR 

MPMSUP 

.1 

- 

+ 

+ 

+ 

+ 

+ 

MSGFMT 

.1 

- 

- 

- 

+ 

MSGFMT 

MSGFMT 

NETFWD 

.3 

- 

- 

- 

+ 

+ 

+ 

NETLOD 

.3 

- 

- 

- 

+ 

NETLOD 

NETLOD 

NETMGR 

.9 

- 

- 

- 

NETMGR 

NETMGR 

NETMGR 

NETREQ 

1.6 

- 

- 

- 

+ 

NETREQ 

NETREQ 

NETSVC 

1.8 

- 

- 

- 

NETSVC 

+ 

+ 

NETTBL 

.0 

- 

- 

- 

NETTBL 

NETTBL 

NETTBL 

NONFIL 

.2 

NONFIL 

NONFIL 

NONFIL 

NONFIL 

NONFIL 

NONFIL 

OSLOAD. 


■ DSLDN)^ 

_r_ 

_ _ _ _ _ _ _ 

- _ _ - - 

_ _ _ 

— 
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Module 1 

K 

1 T.nADR 1 

STNGL _l_ 

.SSQQL^l. 

MASTR^ J- 


■ BLAyjC_ 

OSNTRY 

.5 

OSNTRY 

OSNTRY 

OSNTRY 

OSNTRY 

OSNTRY 

OSNTRY 

PATCH 

.1 

+ 

+ 

+ 

+ 

+ 

+ 

PGMLOD 

1.0 

- 

PGMLOD 

PGMLOD 

PGMLOD 

PGMLOD 

PGMLOD 

QUEMGR 

1.3 

- 

- 

— 

+ 

+ 

+ 

RTCMGR 

.1 

- 

RTCMGR 

RTCMGR 

RTCMGR 

— 

RTCMGR 

RTCNUL 

.1 

+ 

+ 

+ 

+ 

+ 

+ 

SGLUSR 

.1 

- 

SGLUSR 

SGLUSR 

- 

— 

SGLUSR 

SPLMSG 

.1 

— 

- 

SPLMSG 

SPLMSG 

SPLMSG 

SPLMSG 

SPOOLR 

.6 

- 

- 

SPOOLR 

SPOOLR 

SPOOLR 

SPOOLR 

SUBMIT 

.2 

- 

+ 

+ 

+ 

+ 

+ 



_r_ 







Optional Modules To supplement the standard packages, certain 

optional modules (marked by "+" in the matrix 
above) may have to be added. The following 
table explains where these optional modules 
are required: 


I Module I _ 


I CONREM 
I CPMSUP 
I MPMSUP 
I MSGFMT 
I NETFWD 
1 NETLOD 
I NETREQ 
I PATCH 
I QUEMGR 
I RTCNUL 
I SUBMIT 


Network masters with no console (instead of CONDR^). 
To support C“fcns 7, 8, 24, 28, 29, 31, 37 and 107. 
To support C“fcns 134-143, 153, 160 and 161. 

Network masters that make requests over the network. 
To support forwarding of network messages. 

Network masters that load programs over the network. 
Network masters that make requests over the network. 
Wherever a supplementary patch area is required. 

To support MP/M queue emulation (C-fcns 134-140.) 
Wherever no RTC driver is available. 

To emulate CP/M processing of $$$.SUB. 
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Memory Required 


To estimate the memory required by a particu¬ 
lar TurboDOS configuration, you need to take 
into account the combined size of all func= 
tional modules, driver modules, disk buffers, 
and other dynamic storage. 


Drivers typically require IK to 4K, and can 
be even larger if the hardware is especially 
complex. Disk buffer space should be as 
large as possible for optimum performance, 
especially in a network master. About 4K of 
disk buffer space is reasonable for a single- 
user system, although less can be used in a 
pinch. Other dynamic storage doesn't usually 
exceed IK in single-user systems, 2K in net¬ 
work masters. 


The following table gives typical memory 
requirements for standard TurboDOS configura¬ 
tions: 


I_LOADED J13GL-SPPOL- MASTK 


0/S 

lOK 

17K 

19K 

25K 

13K 

22K 

Drivers 

2K 

2K 

2K 

3K 

IK 

2K 

Buffers 

4K 

4K 

4K 

16K 

- 

4K 

Dynamic 

IK 

IK 

IK 

3K 

2K 

2K 

Total 

17K 

24K 

26K 

47K 

16K 

30K 
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Other Languages To facilitate translation into languages 

other than English, TurboDOS has been 
implemented with all textual messages 
segregated into separate modules. All such 
message modules are available in source form 
to TurboDOS OEM licensees upon request. 


The following modules contain all TurboDOS 
operating system messages: 


1 Module I 

Contain.s_ 


1 LCLMSG 

Most operating system messages. 


1 SPLMSG 

Spooler error messages. 


1 LDRMSG 

Loader messages for OSLOAD.CMD. 



In addition, a separate message module is 
available for each TurboDOS command. 
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SYSTEM GENERATION 


This section explains the TurboDOS system 


irsir 




XW Vt^ O W X X An? 


how to use TLINK to link a desired set of 
TurboDOS modules together, and details the 
numerous system patch points which may be 
modified during system generation. Step-by- 
step procedures and examples are provided. 


Introduction The functional modules of TurboDOS are dis¬ 

tributed in relocatable object form (.0 
files). Hardware-dependent driver modules 
are furnished in the same fashion. The 
TurboDOS TLINK command is a specialized 
linker used to bind the desired combination 
of modules together into an executable 
version of TurboDOS. TLINK also includes a 
symbolic patch facility used to modify a 
variety of operating system parameters. 

To generate a complete TurboDOS system, you 
typically must use TLINK several times. At 
minimum, you have to generate both a loader 
OSLOAD.CMD and a master operating system 
OSMASTER.SYS. For a networking system you 
also have to generate a slave operating 
system OSSLAVE.SYS. Complex networks may 
require generation of several different slave 
or master configurations. Finally, you may 
have to use TLINK to generate a cold-start 
bootstrap routine for the start-up PROM or 
boot track. 

At cold-start, the bootstrap routine loads 
the loader program OSLOAD.CMD into the TPA of 
the master computer and executes it. OSLOAD 
loads the master operating system from the 
file OSMASTER.SYS into memory. The master 
operating system then down-loads the slave 
operating system from the file OSSLAVE.SYS 
over the network into each slave computer. 
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The TLINK command is a specialized linker 
used for 8086 TurboDOS system generation, and 
may also be used as a general-purpose linker 
for object modules produced by the TurboDOS 
assembler TASM. 


I TLINK inputfn {outputfn} {-options} 


The TLINK command links a specified collec¬ 
tion of relocatable object modules together 
into a single executable file. The "inputfn 
argument identifies the two input files used 
by TLINK; a configuration file "inputfn.GEN 
and a parameter file "inputfn.PAR". The 
"outputfn" argument specifies the name of the 
executable output file to be created (normal¬ 
ly type .CMD or .SYS). If "outputfn"^ is 
omitted from the command, then "inputfn is 
also used as the name of the executable out¬ 
put file, and should include an explicit file 
type (.CMD or .SYS). 

If the .GEN file is found, it must contain 
the list of object modules (.0 files) to be 
linked together. If the configuration file 
is not found, then TLINK operates in an 
interactive mode. You are prompted by an 
asterisk * to enter a series of directives 
from the console. The syntax of each direc¬ 
tive (or each line of the .GEN file) is; 


I objfile {,objfile}... {,‘comment) I 

The object files are assumed to have type .0 
unless a type is given explicitly. A null 
directive (or the end of the .GEN file) ter¬ 
minates the prompting sequence and causes 
processing to proceed. 
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1? vr\1 a na 4- *1 r\r\ 

u w a. VAA 

(Continued) 


Options 


After obtaining the list of modules from the 
file or console, TLINK links all of the 
modules together, a two-pass process that 
displays the name of each module as it is 
encountered. When the linking phase is com¬ 
plete, TLINK looks for a parameter file 
“inputfn.PAR" and processes it if present 
(described below). Finally, the executable 
file (.CMD or .SYS) is written out to disk. 

NOTE; Each module of the TurboDOS operating 
system is magnetically serialized with a 
unique serial number. The serial number 
consists of two components: an "origin 
number" which identifies the issuing TurboDOS 
licensee, and a "unit number" which uniquely 
identifies each copy of TurboDOS issued by 
that licensee. When used for TurboDOS 
operating system generation, TLINK verifies 
that all modules to be linked are serialized 
consistently, and serializes the executable 
file accordingly. 

Options are always preceded by a "-" prefix, 
and may appear before, between, or after the 
file names. Several options may be concate¬ 
nated after a single "-" prefix. 


1 Option 1 

Explanatioii . _ 


1 -8 

Force 8080 model (single group) 


1 -B 

No 128-byte base page 


1 -C 

List to console, not to printer 


1 -D 

Force data group G-Max to 64K 


1 -H 

No .CMD header (implies -8, -B) 


1 -L 

Listing only, no output file 


1 -M 

List link map 


1 -R 

List inter-module references 


1 -s 

List sorted symbol table 


1 -U 

List unsorted symbol table 


1 -X 

Diagnose undefined references 
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Parameter File TLINK includes a symbolic patch facility that 

may be used during TurboDOS system generation 
to override various operating system para¬ 
meters and to effect necessary software cor¬ 
rections. Patches must be stored in a .PAR 
file. The syntax of each .PAR file entry is: 


I location = value {,value}... {;comment} I 


where the "value" arguments are to be stored 
in consecutive memory locations starting with 
the address specified by "location". 

The "location" argument may be the name of a 
public symbol, an integer constant, or an 
expression composed of names and integer 
constants connected by + or - operators. 
Integer constants must begin with a digit to 
distinguish them from names. Constants of 
the form "Oxdddd" are taken to be hexadeci¬ 
mal. Constants of the form "Odddddd" are 
taken to be octal. Constants that start with 
a nonzero digit are taken to be decimal. The 
"location" expression must be followed by an 
equal-sign = character. 

The "value" arguments may be expressions (as 
defined above) or quoted ASCII strings, and 
must be separated by commas. A "value" ex¬ 
pression is stored as a 16-bit word if its 
value exceeds 255 or if it is enclosed in 
parentheses (...) or brackets [...I; other¬ 
wise, it is stored as an 8-bit byte. An 
expression enclosed in brackets is treated as 
IP-relative (for example, the target address 
of a CALL or JMP instruction). A quoted 
ASCII string must be enclosed by quotes 
"...", and is stored as a sequence of 8-bit 
bytes. Within a quoted string, ASCII control 
characters may be specified by using TASM 
backslant escape sequences. 
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Example 


In the following example, TLINK is used to 
link a single~‘User TurboDOS system for an IBM 
Personal Computer, using the modules listed 
in OSMASTER.GEN and patches in OSMASTER.PAR, 
creating the executable file OSMASTER.SYS. 


Copyright 1984, Software 2000, Inc. 

* ; Single-user without spooling for 

* ; IBM Personal Computer with 256K RAM 


* STDSINGL 

* CPMSUP 

* CONIPC 

* LSTACA 

* NITIPC 

* DSKIPC 

* MSTIPC 

* RTCIPC 


Standard single-user pkg. 
seldom-used CP/M functions 
IBM PC console driver 
IBM PC serial list driver 
IBM PC initialization 
IBM PC floppy disk driver 
IBM PC 256K mem spec table 
IBM PC real-time clock drvr 


Pass 1 

LCLUSR LCLTBL CMDINT AUTLOD SGLUSR etc. 
Pass 2 

LCLUSR LCLTBL CMDINT AUTLOD SGLUSR etc. 

Processing parameter file: 

; Patches for single-user w/o spooling 
OSMLEN = 1024 ;dynamic memory area (16K) 
OSMTOP = 0x1000 ;but limit to first 64K 


AUTUSR 

NMBUFS 

EOPCHR 

SRHDRV 

PRTMOD 


0x80 

8 

OxlA 

1 

0 


logon to user 0 privileg. 
number of disk buffers 
end-of-print character 
search drive A 
direct printing mode 


Writing output file AtOSMASTER.SYS 
OA) 
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Error Messages 



Serial number violation 
Not enough memory 
No object files specified 
Can't open object file 
Non-privileged user 
Unexpected EOF in object file 
Bad token in object file: <type> 
Can't create output file 
Can't write output file 
Load address out-of-bounds 
Duplicate transfer address 
Duplicate def; <name> 

Undefined name: <name> 

Too many externals in module 
Name table overflow 
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Patch Points The following table describes various public 

eTTTnKrkl e in n r Kn DH .Q whinh VOU HiaV Wish to 

modify using the symbolic patch facility of 
TLINK. (Other patch points may exist in 
hardware-dependent drivers, but they are 
beyond the scope of this document.) 

I Sy mboiTl _-IJ. 1 

I • 

I ABTCHR = 0x03 ;CTRL-C CONTBL I 

I Abort character (after attention). I 


ATNBEL = 0x07 ;CTRL-G CONTBL 

Attention-received warning character. 


ATNCHR = 0x13 ;CTRL-S CONTBL 

Attention character. May be patched to 
another character if the default value of 
CTRL-S is needed by application programs. 
A common choice is zero (NUL), which al¬ 
lows the console BREAK key to be used as 
an attention key. 


AUTUSR = OxFF AUTLOG 

Automatic log-on user number. Default 
value of OxFF requires that user log-on 
via LOGON command. If automatic log-on 
desired at cold-start, patch AUTUSR to 
the desired user number (0-31), and set 
the sign-bit if a privileged log-on is 
desired. Generally patched to 0x80 in 
single-user systems to cause automatic 
privileged log-on to user zero. 


2-7 





TurboDOS 1.4 8086 SYSTEM GENERATION 

Implementor's Guide 

Patch Points 
(Continued) 


Copyright 1984 by Software 2000, Inc. 
All rights reserved. 


Patch Points 
(Continued) 


1 Symboll j_- 

I BFLDLY = (300) FLUSHR 

I Buffer flush delay determines how often 
I disk buffers are written to disk, stated 
I in system "ticks'*. Default value (300 
I decimal) causes buffers to be flushed 
I about every five seconds (assuming 60 
I ticks per second). 


BUFBAS = (0000) BUFMGR 

Base paragraph address of external disk 
buffer area (see BUFLEN). 


BUFLEN = (0000) BUFMGR 

Length (in paragraphs) of external disk 
buffer area starting at BUFLEN. Default 
value (0000) indicates that buffers are 
to be allocated from the regular dynamic 
memory pool (see OSMLEN, OSMTOP). 


BUFSIZ = 3 BUFMGR 

Default disk buffer size (0=128, 1=256, 
2=512, 3=1K,..., 7=16K). Default value 
specifies IK disk buffers. 
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Patch Points i Symbcl__l _- 

(Continued) i ‘ 

I CKTAST = (0x0000),(CKTDRA), NETTBL I 

I (0x0100),(CKTDRB), I 

I (0x0200),(CKTDRC), I 

I (0x0300),(CKTDRD) I 

I i 

I Circuit assignment table defines network ! 

I topology. Contains NMBCKT two-word en- 1 

I tries, one for each network circuit to I 

I which this processor is attached. The I 

I first word of each entry specifies the I 

I network address by which this processor I 

I is known on a particular circuit, and the I 
I second word specifies the entrypoint ad- I 
I dress of the circuit driver responsible I 

I for that circuit. (Possibly several cir- I 
I cuits may be handled by the same driver.) I 


CLBLEN =157 CMDINT 

Command line buffer length defines long¬ 
est permissible command line. The de¬ 
fault value permits two 80-char lines. 


CLPCHR = CMDINT 

Command line prompt character. 

CLSCHR = "W^ ^ CMDINT 

Command line separator character. 


COLDFN = 0,"COLDSTRT",”AUT" AUTLOD 

File name and drive for cold-start auto¬ 
load processing (in FCB format). 
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Patch Points 
(Continued) 


symboVl _j^ieiault- -L 

COMPAT = 0 FILCOM 

Default compatibility flags which define 
rules to be used for file-sharing. Patch 
to 0xF8 to relax most MP/M restrictions. 


CONAST = 0,(CONDRA) CONTBL 

Console assignment table defines how con¬ 
sole I/O is handled. First byte passed 
to console driver, and commonly defines 
the channel number (e.g., serial port) to 
be used for the console. Following word 
specifies the entrypoint address of the 
console driver to be used. 


CPMVER = 0x31 NONFIL 

CP/M BDOS version number returned by 
C-function 12 in BL-register. 


DEFDID = (0) NETTBL 

Default network destination ID, used for 
routing all network requests that are not 
related to a particular disk drive, queue 
or printer. In a slave, DEFDID should be 
set to the network address of the master. 
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Patch Points 
(Continued) 


l _^yiRbol_ J __I 

I I 

I I 

I DSKAST = 0,(DSKDRA),1,(DSKDRB), DSKTBL I 
I OxFF,(0),0xFF,(0),... I 

I Disk assignment table, an array of 16 I 
I three-byte entries (one for each drive I 
i letter A-P) that defines which drives are ! 
I local, remote, and invalid. I 

I For a local drive, the first byte must I 
I not have the sign-bit set. That byte is I 
I passed to the disk driver, and is common- I 
I ly used to differentiate between multiple I 
I drives connected to a single controller. I 
I The following word specifies the entry- I 
I point address of the disk driver to be I 
1 used. I 

I For a remote drive, the first byte must I 
I have the sign-bit set. The low-order I 
I bits of that byte specify the drive let- I 
I ter to be accessed on the remote proces- i 
I sor. The following word specifies the I 
I network address of the remote processor. I 

I For an invalid drive, the first byte must I 
I be OxFF, and the following word should be I 
I (0). I 

I NOTE; In slave configurations STDSLAVE I 
I and STDSLAVX, the default values are; I 

I DSKAST = 0x80,(0),0x81,(0), I 
I 0x82,(0),0x83,(0), I 
I ...,0x8E,(0),0x8F,(0) I 
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Patch Points 
(Continued) 


I Ryml^T 'i_Reiault-yAlJAg-LJlfidiale- 

1 DSPPAT = 1,1/1/...#1 LSTTBL 

I De-spool printer assignment table, an ar- 
I ray of 16 bytes (one for each printer 
I letter A-P) that defines the initial 
1 queue to which each printer is assigned. 

1 Values 1 through 16 correspond to queues 
I A-P, and 0 means that the printer is off- 
r line. The default value assigns all 
I printers to queue A. 


ECOCHR = 0x10 ;CTRL-P CONTBL 

Echo-print character (after attention). 


EOPCHR = 0 LSTTBL 

End-of-print character. May be patched 
to any non-null character, in which case 
the presence of that character in the 
print output stream will automatically 
signal an end— of—print—job condition. 

The value zero disables this feature. 




(Ox^FF^ , NETTBL 

(^F^) ,g^F^ 

Network forwarding table, an array of 
two—byte entries that define any explicit 
message forwarding routes to be used by 
this processor. The first byte of each 
entry specifies a "foreign" circuit num¬ 
ber N, and the second byte a "domestic" 
circuit number C. Any messages destined 
for circuit N will be routed via circuit 
C. This table is variable-length, termi¬ 
nated by OxFF, and defaults to empty. 
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Patch Points 
(Continued) 


I _ Symbol. J_Oeiaiili:- I 

I LDCOLD = OxFF AUTLOD I 

I Cold-Start autoload enable flag. Patch I 
I to zero if you want to disable the cold- i 
I start autoload feature (COLDSTRT.AUT). I 


LDWARM = OxFF AUTLOD 

Warm-start autoload enable flag. Patch 
to zero if you want to disable the warm- 
start autoload feature (WARMSTRT.AUT). 





LOADFN = 0,"OSMASTER","SyS" OSLOAD 

Default file name and drive (in FCB for¬ 
mat) loaded by OSLOAD.COM. Drive field 
(FCB byte 8) may be patched to an expli¬ 
cit drive value to inhibit scanning. 


LOGUSR = 31 FILCOM 

User number for logged-off state. 


MAXMBS = 0 NETMGR 

Maximum number of message buffers that 
will ever be allocated. Default value of 
0 means number of message buffers is 
limited only to size of available memory. 


(^*901 o') i iabk / 

-Oy^poo - Oy ooH 6) • oS f T?/! 

T |jf3 U > (tf/ ^ 

^ (Oy/ooo) 
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Patch Points 
(Continued) 


I Syml^l J _Default Value- LMoAll g. 

I MAXRPS = 0 NETMGR 

I Maximum number of reply packets that will 
I ever be allocated. Default value of 0 
I means number of reply packets is limited 
I only to the size of available memory. 


\ NHBCKT = 1 NETTBL 

I 

I Number of network circuits to which this 
I processor is connected. 


NMBMBS = 0 NETMGR 

Number of message buffers pre-allocated 
at cold-start. Message buffers are allo¬ 
cated dynamically as needed, but this may 
cause fragmentation which prevents you 
from changing the size of the disk buffer 
pool with the BUFFERS command. If this is 
important, patching NMBMBS to a suitable 
positive value will eliminate the problem 
(twice the number of network nodes is a 
good starting value to try). 


NMBRPS = 0 NETMGR 

Number of reply packets pre-allocated at 
cold-start. Reply packets are allocated 
dynamically as needed, but this may cause 
fragmentation which prevents you from 
changing the size of the disk buffer pool 
with the BUFFERS coinmand. If this is 
important, patching NMBRPS to a suitable 
positive value will eliminate the problem 
(the number of network nodes is a good 
starting value to try). 
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Patch Points 
(Continued) 


^1V 4ti n 7 

I n 

1/7 



NMBSVC = 2 NETSVC 


Number of network server processes to be 
activated. (The number of network nodes 
is a good starting value to try.) 


NMBUFS = 4 BUFMGR 

Default number of disk buffers allocated 
at cold-start. Must be at least 2. For 
optimum performance, allocate as many 
buffers as possible (consistent with TPA 
and other memory requirements). 


OSMLEN = (128) ;2K bytes MEMMGR 

Length (in paragraphs) of the memory area 
to be allocated immediately above the 
TurboDOS operating system resident for 
dynamic working storage. This area must 
accomodate disk buffers if no external 
disk buffer area is defined (BUFLEN is 
zero). The default value (128 paragraphs 
or 2K bytes) is appropriate for a simple 
slave with no disk buffers. For other 
configurations, patch OSMLEN to a value 
large enough to accomodate dynamic memory 
needs. Divide required length in bytes 
by 16 to give the value of OSMLEN in 
paragraphs. (See OSMTOP.) 
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Patch Points 
(Continued) 


I Symbol ~l _Defa ult Vallie- - 

I OSMTOP = (0000) MEMMGR 


|J0 ^ 


I* 




otV^ 


Absolute upper bound (paragraph address) 
for dynamic working storage area. The 
actual upper bound is either OSMTOP or 
the top of TurboDOS plus OSMLEN, which¬ 
ever is smaller. The default value of 
zero indicates no specified upper bound. 


PRTCHR = OxOC ?CTRL-L CONTBL 


End-print character (after attention). 
This is a console attention-response, not 
to be confused with EOPCHR. 


PRTMOD = 1 LCLTBL 

Initial print mode for local user. The 
default value of 1 specifies spooling. 
Patch to 0 for direct, or 2 for console. 
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Patch Points l _^yiiibx>J^ J _ 

I I 

WrVlluxliUcG# I 

I PTRAST = 0,(LSTDRA)rOxFF,(0), LSTTBL 

I OxFF,(0),0xFF,(0),... 

I 

I Printer assignment table, an array of 16 
I three-byte entries (one for each printer 
I letter A-P) that defines which printers 
I are local, remote, and invalid. 

I 

I For a local printer, the first byte must 
I not have the sign-bit set. That byte is 
I passed to the disk printerr, and is com- 
I monly defines the channel number (e.g., 

I serial port) to be used for the printer. 

I The following word specifies the entry- 
I point address of the printer driver. 

I 

I For a remote printer, the first byte must 
I have the sign-bit set. The low-order 
I bits of that byte specify the printer 
I letter to be accessed on the remote pro- 
I cessor. The following word specifies the 
I network address of the remote processor. 

I 

I For an invalid printer, the first byte 
1 must be OxFF, and the following word 
i should be (0). 

I 

I NOTE: In slave configurations STDSLAVE 
I and STDSLAVX, the default values are: 

I 

I PTRAST = 0x80,(0),0x81,(0), 

I 0x82,(0),0x83,(0), 

I ...,0x8E,(0),0x8F,(0) 
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Patch Points 
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I .gymboi 1 _ Default, Valu e_1 1 

I QUEAST = 0,(0)fOxFF,(0), LSTTBL I 

I OxFF,(0)rOxFF,(0),... I 

I Queue assignment table, an array of 16 I 
I three-byte entries (one for each queue I 
I letter A-P) that defines which queues are I 
I local, remote, and invalid. I 

r For a local queue, all three bytes must \ 

I be set to zero. I 

I For a remote queue, the first byte must I 
I have the sign-bit set. The low-order I 

I bits of that byte specify the queue let- I 
I ter to be accessed on the remote proces- I 
I sor. The following word specifies the I 

I network address of the remote processor. I 
I I 

I For an invalid queue, the first byte must I 
I be OxFF, and the following word should be I 
I (0) . I 

I NOTE; In slave configurations STDSLAVE I 
I and STDSLAVX, the default values are: I 

I QUEAST = 0x80,(0),0x81,(0), I 

I 0x82,(0),0x83,(0), I 

I ...,0x8E,(0),0x8F,(0) I 


QUEDLY = (0000) QUEMGR 

Polling delay used in unconditional Read 
Queue (when queue is empty) and Write 
Queue (when queue is full), stated in 
system "ticks". If RTC driver is avail¬ 
able, patch to largest delay that yields 
reasonable queue performance. 
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Patch Points 
(Continued) 




QUEDRV = OxFF QUEMGR 

Drive used for FIFOs that emulate MP/M 
queues. Default value OxFF means use the 
system disk (disk from which TurboDOS was 
loaded at cold-start). Patch to 0 - 15 
to specify a particular drive A-P. 


QUEPTR = 1 LCLTBL 

Initial queue or printer assignment. If 
PRTMOD = 1 (spooling), QUEPTR specifies a 
queue assignment. If PRTMOD = 0 (direct) 
QUEPTR specifies a printer assignment. 

In both cases, values 1 through 16 corre¬ 
spond to letters A-P, and zero means do 
not queue or print off-line. 


RCNMSK = OxFF MPMSUP 

Mask used in deriving a console number 
from a network node in C-function 153. 


RCNOFF = 0 MPMSUP 

Offset used in deriving a console number 
from a network node in C-function 153. 


RESCHR = 0x11 ;CTRL-Q CONTBL 

Resume character (after attention). 
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Patch Points 
(Continued) 


Symbol-J. 




I SCANDN = 0 


1 Module- 
OSLOAD 


Scan direction flag for OSLOAD. Patch to 
OxFF to scan P-to-A (instead of A-to-P)• 


SLVFN = "OSSLAVE ", 


" "SYS" 


NETSVC 


Name and type of file (in FCB format) to 
be down-loaded into slave processors. 


SPLDRV = OxFF 


LCLTBL 


Initial spool drive. Default value OxFF 
indicates spool to system disk (disk from 
which TurboDOS was loaded at cold-start). 
Patch to 0 - 15 to specify drive A-P. 


SRHDRV = 0 


CMDINT 


Search drive for command files. Patch to 
value 1 through 16 to search drive A-P 
if command is not found on current 
(default) drive. Patch to OxFF to search 
system disk (disk from which TurboDOS was 
loaded at cold-start). Default value 0 
disables this feature altogether. 


SUBFN = 0,"$$$ ","SUB" SUBMIT 

FCB for emulating CP/M submit files. 


WARMFN = 0,"WARMSTRT","ADT' 


AUTLOD 


I File name and drive for warm-start auto- I 
1 load processing (in FCB format). | 
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Network Operation TurboDOS accomodates a wide variety of net¬ 
work topologies, ranging from the simplest 
point-to-point master/slave networks to the 
most complex star, ring, and hierarchical 
structures. 


Network Model A TurboDOS network is defined to consist of 

up to 255 clxcult3 , with up to 255 iijpAe.& 
(processors) on each circuit. Each node has 
a unique 16-bit ne±w^xJc addxe.s^ consisting of 
an 8-bit circuit number plus an 8-bit node 
number (on that circuit). 

Any processor may be connected to several 
circuits, if desired. A processor connected 
to multiple circuits has multiple network 
addresses, one for each circuit. Such a 
processor even may be set up to perform mes¬ 
sage forwarding from one circuit to another, 
permitting dialogue between network nodes 
that do not share a common circuit between 
them (more on this later). 


Network Tables The actual network topology is defined by a 

series of tables in each processor. The 
tables are set up during system generation, 
and define the network as "seen" from the 
viewpoint of each processor. The tables are: 


^^mbDl-J __ 

NMBCKT A byte value that defines the 
number of network circuits to 
which this processor is connec¬ 
ted. 
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Network Tables 
(Continued) 


i Symbol. J _ PeggJlpti^ - 

I CKTAST The circuit assignment table 
I containing NMBCKT entries defin- 

I ing the network address by which 

I this processor is known on each 

I circuit, and specifying the net- 

I work circuit driver responsible 

I for each handling each circuit. 

IdsKASTT he disk assignment table that 
I specifies for all drive letters 

I A~P which are local, remote, and 

I invalid. This table specifies 

I a network address for each re- 

1 mote drive, and a disk driver 

I for each local drive. 

I PTRAST The printer assignment table 
I that specifies for all printer 

1 letters A-P which are local, re- 

1 mote, and invalid. This table 

I specifies a network address for 

I each remote printer, and a prin- 

I ter driver for each local prin- 

I ter. 

I QUEAST The queue assignment table that 
I specifies for all queue letters 

I A-P which are local, remote, and 

I invalid. This table specifies a 

1 network address for each remote 

I queue. 

I DEFDID The default network destination 
I ID, used for routing all network 

I requests that are not related to 

I a specific disk drive, printer, 

I or queue. 
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Symbol 1 

_ D£SiJj:lpi:ioii _ _ 

FWDTBL 

The message forwarding table 
that specifies any additional 
circuits (not directly connected 
to this processor) which may be 
accessed via explicit message 
forwarding, and how messages 
destined for such circuits are 
to be routed. 


These tables are pre~defined with default 
values to make set-up of simple master/slave 
networks very easy. For complex multi¬ 
circuit networks, the set-up is somewhat more 
complicated (as might be expected). 

Refer to the preceding Pajt^li sub¬ 
section for details of the organization and 
defaults for these network tables. 
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Message Forwarding 


The TurboDOS module NETFWD supports both 
"implicit" and "explicit" forwarding of net¬ 
work messages. To understand the distinc¬ 
tion, consider the case of a network with 
three processors (PI, P2, and P3) connected 
by two circuits (Cl and C2) as follows: 


I PI I-Cl-I P2 I-C2-1 P3 


A program running in PI makes an access to 
drive D. Suppose the disk assignment tables 
in the three processors are set up in the 
following fashion: 

. Pl*s DSKAST defines its drive D as a 
remote reference to P2*s drive B. 

. P2*s DSKAST defines its drive B as a 
remote reference to P3's drive A. 

. P3*s DSKAST defines its drive A as a 
local device attached directly to P3. 

In this case. Pi's access to its drive D 
actually winds up implicitly accessing P3's 
drive A. This is impJJ.x;lt forwarding. 

Alternatively, suppose Pi's DSKAST defines 
its drive D as a remote reference to P3's 
drive A, and that Pi's FWDTBL provides that 
messages destined for circuit C2 may be 
routed via Cl. In this case, PI sends a 
request to P3 on circuit Cl. P2 receives the 
request, recognizes that it should be forwar¬ 
ded, and retransmits the request to P3 via 
circuit C2. Thus, PI accesses P3|s drive A 
with the assistance of P2, but this time PI 
is not aware of P2*s role in the transaction. 
This is explici.1: forwarding. 
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A Complex Example Let's take a reasonably complex network situ¬ 
ation and see how to construct the required 
.GEN and .PAR files. 

Our hardware is a board-and-bus microcomputer 
system consisting of an 80286 CPU running in 
unmapped (8086) mode, 128K of RAM, hard disk 
and floppy disk subsystems (all these make up 
the master processor), and several single¬ 
board slave computers with 80186 CPUs and 
256K of RAM each. The master processor is 
interfaced to two printers via RS232 serial 
ports: a daisywheel printer on port 0 using 
XON/XOFF protocol and a matrix printer on 
port 1 using clear-to-send handshaking. In 
addition, the master has a high-speed RS422 
interface connecting it to another board-and- 
bus system of similar configuration some 
distance away. 

We want to configure a TurboDOS system for 
this hardware that permits all of the users 
of each system to access the hard disk, 
floppy disks, and printers attached to both 
the local and remote system. We might create 
the following OSMASTER.GEN file; 


; OSMASTER. 
STDMASTR 
NETREQ 
MSGFMT 
CONREM 
LSTXON 
LSTCTS 
DSKHDC 
DSKFDC 
CKTSLV 
CKT422 
RTCDRV 
NITDRV 
MEMTBL 


GEN for complex example 
standard master package 
to make requests of other sys 
needed by NETREQ 
no console on the master 
XON/XOFF for daisy (LSTDRA) 
CTS for matrix (LSTDRB) 

hard disk controller (DSKDRA) 
floppy disk control. (DSKDRB) 
circuit driver for slaves (CO) 
circuit driver for RS422 (Cl) 
real-time clock driver 
hardware initialization driver 
memory specification table 
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A Complex Example 
(Continued) 


Our system generation task is completed by 
creating the companion OSMASTER.PAR file: 


OSMASTER.PAR for complex example 


NMBCKT 
CKTAST = 

DSKAST = 


PTRAST = 


QUEAST = 


DEFDID 

DSPPAT 

OSMLEN 

COMPAT 

NMBSVC 

NMBUFS 


2 ; 2 network circuits: 

(0x0000),(CKTDRA) ; CO = bus 
(0x0100),(CKTDRB) ; Cl = RS422 


0x00,(DSKDRA) 
0x00,(DSKDRB) 
0x01,(DSKDRB) 
0x80,(0x0101) 
0x81,(0x0101) 
0x82,(0x0101) 
0x00,(LSTDRA) 
0x01,(LSTDRB) 
0x80,(0x0101) 
0x81,(0x0101) 
0x00,(0x0000) 
0x00,(0x0000) 
0x80,(0x0101) 
0x81,(0x0101) 
(0x0101) 

1 , 2 , 3,4 
(0x0600) 

0xB8 
5 

20 


drv A=local HD 
drv B=local FDO 
drv C=local FDl 
drv D=remote HD 
drv E=remote FDO 
drv F=remote FDl 
ptr A=lcl daisy 
ptr B=lcl matrix 
ptr C=rmt daisy 
ptr D=rmt matrix 
queue A=local 
queue B=local 
; queue C=remote A 
; queue D=remote B 
default=other master 
assgn ptrs to queues 
24K dynamic memory 
compatibility flags 
5 server processes 
20 IK disk buffers 


The generation of the second master operating 
system could be identical, except that all 
occurrences of network addresses (0x0100) and 
(0x0101) in the OSMASTER.PAR file would be 
reversed. Generation of the slave operating 
system would be very straightforward, and 
identical for both systems. 

If you study this example thoroughly until 
you understand the reason for every .GEN and 
.PAR file entry, you should have little 
trouble setting up your own "sysgens". 
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Sysgen Procedure To conclude this section, here is a suggested 

e4-on-Hv-.e5h^:^n nrocedure for aeneratinq a new 

j_--_ _ _ 

version of TurboDOS: 

1. Bring up a previous version of 8086 
TurboDOS. If this is your first attempt 
to generate an 8086 TurboDOS system, you 
may bring up CP/M—86 instead. However, if 
you are using CP/M, all disks will have to 
be in a format compatible with both CP/M 
and TurboDOS (e.g., eight-inch one-sided 
single-density with 128-byte sectors). 

2. Make a working copy of your TurboDOS dis¬ 
tribution disk. Do not use the original 
disk (in case something goes wrong). 
Insert the working diskette in a conven¬ 
ient disk drive. 

3. Using your favorite text editor, create or 
revise the file OSMASTER.GEN containing 
the names of the relocatable modules to be 
linked together. Generally, this will 
consist of the appropriate STDxxxxx stan¬ 
dard package plus selected additional 
modules and all required device drivers. 

4. Using your editor once again, create or 
revise the file OSMASTER.PAR containing 
any required patches. This may be omitted 
if no patches are desired. 

5. Using the command TLINK__OB .M AST £R*.SX£f 
generate an executable master operating 
system in accordance with the .GEN and 
.PAR files, 

6. In a similar fashion, construct a new 
loader by creating or revising the files 
OSLOAD.GEN and OSLOAD.PAR, then using the 
command TLINK.X) SLOAD^GM^ to generate the 
executable loader. 
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Sysgen Procedure 7. For a master/slave network system, con¬ 
struct a slave operating system in the 
same manner. Create or revise the files 
OSSLAVE.GEN and OSSLAVE.PAR, then use the 
command TLINILOS^JiAyE.sy£ to generate the 
down-loadable slave operating system. 

8. To test the newly-generated system, eject 
all disks other than your working disk 
(again, in case something goes wrong). 
Enter the command OSliOAP . The new system 
should cold-start. If it fails to come up 
or to function properly, you will have to 
start over at step 1 and check your work 
carefully — there is most likely an error 
in one of your .GEN or .PAR files, or a 
"bug" in one of your drivers. 
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DISTRIBUTION This section explains the TurboDOS distribu¬ 

tion procedure in detail. It covers TurboDOS 
licensing requirements/ and the obligations 
of licensed distributors/ dealers/ and end- 
users. It describes how to make up and 
serialize TurboDOS distribution disks. 

Although this section is of concern primarily 
to licensed TurboDOS distributors/ we've 
included it here so that dealers and end- 
users can gain a better perspective on the 
overall distribution process. 


TurboDOS Licensing TurboDOS is a proprietary software product of 

Software 2000/ Inc. As such/ it is protected 
by law against unauthorized use and reproduc¬ 
tion. Authorization to use and/or reproduce 
TurboDOS is granted only by written license 
agreement. 


Legal Protection TurboDOS programs and documentation are copy¬ 
righted, which means it is against the law to 
make copies without express written authori¬ 
zation from Software 2000 to do so. 

The word "TurboDOS" is a trademark owned by 
Software 2000 and registered in Class 9 (com¬ 
puter software) and Class 16 (documentation) 
with the trademark offices of the United 
States and most of the developed countries of 
the free world. This means it is against the 
law to make use of the TurboDOS trademark 
without express written authorization from 
Software 2000. 

Software 2000 has licensed certain companies 
to distribute TurboDOS. Such distributors 
are authorized to use the TurboDOS trademark, 
and to teproduce, distribute, and sub-license 
TurboDOS programs and documentation to deal¬ 
ers and end-users. 
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User Obligations TurboDOS may be used only after the user has 

paid the required license fee, signed a copy 
of the TurboDOS end-user license agreement, 
and returned the signed agreement to the 
issuing TurboDOS distributor. Then, TurboDOS 
may be used only in strict conformance with 
the terms of the license. 

Each end-user license allows TurboDOS to be 
used on one specific computer system identi¬ 
fied by make, model, and serial number# The 
end-user license may not be transferred from 
one computer system to another, and expressly 
forbids copying programs and documentation 
except as required for backup purposes only. 

A separate license fee must be paid and a 
separate license signed for each computer 
system on which TurboDOS is used. Network 
slave computers that cannot operate stand¬ 
alone do not have to be licensed separately 
from the network master. (This would be the 
case, for example, if the slave computers 
have no local disk storage, or if TurboDOS is 
furnished in a form that cannot be run stand¬ 
alone on the slave computers.) However, 
networked computers that are also capable of 
stand-alone operation under TurboDOS must 
each be licensed separately. 


Dealer Obligations A dealer must sign a TurboDOS dealer agree¬ 
ment and return the signed agreement to the 
issuing distributor. Then, the dealer is 
permitted to purchase pre-serialized copies 
of TurboDOS programs and documentation from 
the distributor, and to resell them to end- 
users. Dealers may not reproduce TurboDOS 
programs or documentation for any purpose. 
Before delivering each copy of TurboDOS, the 
dealer must see to it that the end-user signs 
the TurboDOS end-user license agreement and 
returns it to the issuing distributor. 
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Distributor 

Obligations 


Each licensed TurboDOS distributor is provi- 
cec a masrer copy of iuljjui^wo 
modules and command programs on diskette. A 
distributor is allowed to reproduce and 
distribute copies of TurboDOS to dealers and 
end-users, but only in connection with 
certain specifically authorized hardware 
(usually manufactured or sold by the distri¬ 
butor). The distributor is required to 
serialize each copy of TurboDOS with a unique 
sequential magnetic serial number, and to 
register each serial number promptly with 
Software 2000. (Serialization is described 
in more detail below.) 

Each distributor is also provided with a 
master copy of TurboDOS documentation, either 
in camera-ready hardcopy or in ASCII files on 
disk. The distributor is responsible for 
reproducing the documentation and furnishing 
it with each copy of TurboDOS it issues. 

A distributor must require each dealer to 
sign and return a TurboDOS dealer agreement 
before issuing copies of TurboDOS to the 
dealer for resale. A distributor must 
require each end-user to sign and return a 
TurboDOS end-user license agreement before 
issuing a copy of TurboDOS directly to the 
end-user. 
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Serialization Each copy of TurboDOS is magnetically serial¬ 

ized with a unique serial number. Such 
serialization helps ensure that reproduction 
and distribution of TurboDOS is done in 
strict accordance with the required licensing 
and registration procedures, and facilitates 
tracing of unlicensed copies of the software. 

Each relocatable module of TurboDOS distribu¬ 
ted to a dealer or end-user has a magnetic 
serial number composed of two parts: 

. an origin numbex that identifies the 
issuing distributor, and 

. a sequential un±t nxkmh&L that uniquely 
identifies each copy of TurboDOS issued 
by that distributor. 

During system. generation, the TLINK command 
verifies that all modules making up a Turbo¬ 
DOS configuration are serialized consistent¬ 
ly, and magnetically serializes the resulting 
executable version of TurboDOS accordingly. 

The relocatable modules on the master disk 
furnished to each licensed TurboDOS distribu¬ 
tor are partially serialized with an origin 
number only. Each distributor is provided a 
serialization program (SERIAL.CMD) that must 
be used to add a unique sequential unit num¬ 
ber to each copy of TurboDOS issued by the 
distributor. The TLINK command will not 
accept partially—serialized modules that have 
not been serialized with a unit number. Con¬ 
versely, the SERIAL command will not re¬ 
serialize modules that have already been 
fully serialized. 
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Technical Support Software 2000 maintains telephone and telex 

”hot--lines” to provide TurboDOS technical 
assistance to its distributors. These are 
unlisted numbers providing direct access to 
the authors of the TurboDOS operating system, 
and are furnished only to licensed TurboDOS 
distributors. We encourage distributors to 
take advantage of this service whenever tech¬ 
nical questions or problems arise in using or 
configuring TurboDOS. 

It is the responsibility of each licensed 
distributor to provide technical support to 
its dealers and end-user customers. Software 
2000 assist dealers or end-users 
directly. Where exceptional circumstances 
seem to require direct contact between Soft¬ 
ware 2000 technical personnel and a dealer or 
end-user, this must be handled strictly by 
prior arrangement between Software 2000 and 
the distributor. 
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SERIAL Command The SERIAL command enables TurboDOS distribu¬ 

tors to magnetically serialize relocatable 
modules of TurboDOS for distribution. 


Syntax I I 

I SERIAL srcefile destfile ;Unnn {options} I 
I SERIAL ;Unnn (options) I 


Explanation 


Options 


The SERIAL command works exactly like the 
COPY command, and accepts exactly the same 
arguments and options. However, SERIAL has 
the additional function of magnetically 
serializing relocatable modules as they are 
copied. SERIAL serializes files of type .REL 
(Z80 modules) and type .0 (8086 modules). 
Other files are copied without any change. 

The unit number must be specified on the 
command line as ;Unnn, where "nnn" represents 
a decimal unit number in the range 0-65535. 
Unit numbers must be assigned sequentially, 
starting with 1. Unit number 0 is reserved 
by convention for in-house use by the distri¬ 
butor. 

SERIAL produces fully-serialized modules that 
are encoded with the distributor's origin 
number and the specified unit number. TLINK 
does not accept TurboDOS modules unless they 
have been fully serialized in this fashion. 


_ 

SERIAL accepts all COPY options, plus; 

;Unnn Relocatable modules (type .REL 
or .0) are magnetically serial¬ 
ized with unit number nnn, which 
must be a decimal integer in the 
range 0 to 65535. This "option" 
is mandatory for SERIAL. 


3-6 




^rboDOS 1*4 8086 
Implementor's Guide 




SERIAL Command 
(Continued) 


Copyright 1984 by Software 2000, Inc. 
All rights reserved. 


Example 


I 

i Qa> SERIAL Hi gU289N 

I OA:AUTLOD .0 copied to 0B:AUTLOD .0 

I OA:AUTLOG .0 copied to OBiAUTLOG .0 


OAtSYSNIT .0 copied to 0B:SYSNIT .0 
OA) 


I 


I 


Error Messages 


SERIAL incorporates all COPY error mes¬ 
sages, plus: 

Unit number not specified 
Origin number violation 
File is already serialized 
Unexpected EOF in .0 or .REL file 
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PACKAGE Command The PACKAGE command lets you combine any 

collection of relocatable object modules into 
a single concatenated .0 file. 


Syntax I I 

I PACKAGE srcefile (destfile) I 


Explanation PACKAGE may be used to construct custom 

packages of TurboDOS modules, make additions 
or changes to the supplied STDxxxxx packages, 
pre-package collections of driver modules, 
and so forth. 

The "srcefile" argument specifies the name of 
an input file "srcefile.PKG" that lists the 
modules to be packaged. The "destfile" argu¬ 
ment specifies the name of the concatenated 
.0 file to be created. If "destfile" is 
omitted, then the "srcefile" argument is also 
used as the name of the output ,0 file. 

If the .PKG file is found, it must contain 
the list of relocatable object modules (.0 
files) to be linked together. If the .PKG 
file is not found, then the PACKAGE command 
operates in an interactive mode. You are 
prompted by an asterisk * to enter a series 
of directives from the console. The syntax 
of each directive is: 


I objectfn {,objectfn},,. {;comment) 


A null directive terminates the prompting 
sequence and causes processing to proceed. 

After obtaining the list of modules from the 
file or console, PACKAGE concatenates all of 
the modules together (displaying the name of 
each module as it is encountered) and writes 
the result to the output file. 
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Example 


Error Messages 


i 0A} PACKAGE STDLQADR ! 

I * ; STDLOADR.PKG standard loader package I 
I * OSLOAD,LDRMSG,OSNTRY,FILMGR,FILSUP I 
I * FILCOM,BUFMGR,DSKMGR,DSKTBL,NONFIL I 
I * CONMGR,CONTBL,DSPSGL,COMSUB I 
I OSLOAD LDRMSG OSNTRY FILMGR FILSDP etc. I 
i OA} i 


File name missing from command 
Invalid input file name 
Non-privileged user 
Unexpected EOF in input file 
Disk is full 
Can't make output file 
Can't open input file 
No input files 
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Here is the procedure to be followed by dis¬ 
tributors when creating each copy of TurboDOS 

to be issued to a dealer or end-user: 

1. Assign a unique sequential unit number for 
this copy of TurboDOS, and register it 
immediately by filling out a serial number 
registration card (or agreed-to substi¬ 
tute) and mailing to Software 2000, Inc. 

2. Format a new disk, and label it with the 
following information clearly legible: 

. trademark TurboDOS^ 

. version number (1.4x) 

. origin and unit numbers (oo/uuuu) 

. statutory copyright notice: 

Copyright 198x by Software 2000, Inc. 

All rights reserved. 

3. Use the SERIAL command to copy and serial¬ 
ize the appropriate files from your dis¬ 
tribution master disk to the new disk. 
Use the tables on the following page to 
guide you in determining what files to put 
on the new disk. 

IMPORTANT NOTE: Be absolutely certain 
that the new disk does not contain any 
unserialized modules or SERIAL.CMD! 

4. Using the new serialized disk, use the 
TLINK command to generate an executable 
loader and operating system. Follow the 
system generation procedure described in 
the previous section. 

5. In addition to the serialized disk, you 
should issue copies of TurboDOS documenta¬ 
tion and a start-up PROM (if applicable). 
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Distribution 

Procedure 

(Continued) 


The following table may be used for guidance 
in preparing TuruoiA^o ui»Kc> j-wi. uAotj. 

In addition to the files shown, you need to 
include hardware-dependent driver modules and 
utility programs as appropriate. 

I single-user I single-user 1 multi-user I 


STDLOADR.O 

STDSINGL.O 


STDLOADR.O 

STDSINGL.O 

STDSPOOL.O 


CPMSUP 

MPMSUP 

RTCNUL 

PATCH 

SUBMIT 

OSBOOT 


CPMSUP .0 
MPMSUP .0 
RTCNUL .0 
PATCH .0 
SUBMIT .0 
OSBOOT .0 


AUTOLOAD.CMD AUTOLOAD.CMD 
BACKUP .CMD BACKUP .CMD 

BOOT .CMD BOOT .CMD 
BUFFERS .CMD BUFFERS .CMD 

COPY .CMD COPY .CMD 
DATE .CMD DATE .CMD 
DELETE .CMD DELETE .CMD 


DIR 

DO 

DRIVE 

DUMP 


.CMD DIR .CMD 

.CMD DO .CMD 

.CMD DRIVE .CMD 

.CMD DUMP .CMD 


STDLOADR.O 

STDSINGL.O 

STDSPOOL.O 

STDMASTR.O 

STDSLAVE.O 

STDSLAVX.O 

CPMSUP .0 
MPMSUP .0 
RTCNUL .0 
PATCH .0 
SUBMIT .0 
OSBOOT .0 
NETREQ .0 
NETFWD .0 
QUEMGR .0 
MSGFMT .0 
NETSVC .0 
CONREM .0 


AUTOLOAD 

BACKUP 

BATCH 

BOOT 

BUFFERS 

CHANGE 

COPY 

DATE 

DELETE 

DIR 

DO 

DRIVE 

DUMP 


.CMD 

.CMD 

.CMD 

.CMD 

.CMD 

.CMD 

.CMD 

.CMD 

.CMD 

.CMD 

.CMD 

.CMD 

.CMD 
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Distribution 

Procedure 

(Continued) 



single-user 1 
.w/o_spooler 1 

single-user 1 
.with spooler J. 

multi-user 



ERASEDIR.CMD 

ERASEDIR 

.CMD 

ERASEDIP 

..CMD 



- 


- 


FIFO 

.CMD 



FIXDIR 

.CMD 

FIXDIR 

.CMD 

FIXDIR 

.CMD 



FIXMAP 

.GMD 

FIXMAP 

.CMD 

FIXMAP 

.CMD 



FORMAT 

.CMD 

FORMAT 

.CMD 

FORMAT 

.CMD 



LABEL 

.CMD 

LABEL 

.CMD 

LABEL 

.CMD 



- 


- 


LOGOFF 

.CMD 



- 


- 


logon 

.CMD 



- 


- 


MASTER 

.CMD 



OTOASM 

.CMD 

OTOASM 

.CMD 

OTOASM 

.CMD 



PRINT 

.CMD 

PRINT 

.CMD 

PRINT 

.CMD 



- 


PRINTER 

.CMD 

PRINTER 

.CMD 



- 


QUEUE 

.CMD 

QUEUE 

.CMD 



READPC 

.CMD 

READPC 

.CMD 

READPC 

.CMD 



- 


- 


RECEIVE 

.CMD 



RENAME 

.CMD 

RENAME 

.CMD 

RENAME 

.CMD 



- 


- 


SEND 

.CMD 



SET 

.CMD 

SET 

.CMD 

SET 

.CMD 



SHOW 

.CMD 

SHOW 

.CMD 

SHOW 

.CMD 



TASM 

.CMD 

TASM 

.CMD 

TASM 

.CMD 



TBUG 

.CMD 

TBUG 

.CMD 

TBUG 

.CMD 



TLINK 

.CMD 

TLINK 

.CMD 

TLINK 

.CMD 



TPC 

.CMD 

TPC 

.CMD 

TPC 

.CMD 



TYPE 

.CMD 

TYPE 

.CMD 

TYPE 

.CMD 



VERIFY 

.CMD 

VERIFY 

.CMD 

VERIFY 

.CMD 
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CODING CONVENTIONS This section is devoted to in-depth discus¬ 
sion of TurboDOS internal coding conventions# 
aimed at the systems programmer writing hard- 
ware-dependent drivers or resident processes. 
All coding examples and driver listings in 
this document make use of the TurboDOS 8086 
assembler TASM. 


Undefined External To allow various TurboDOS modules to be in- 
References eluded or omitted at will/ TLINK auto¬ 

matically resolves all undefined external 
references to the default names "DndCode" 
(for code references) and "UndData" (for data 
references). The common subroutine module 
COMSUB contains the following: 


LOG 

Data# 

;data segment 

UndData:: 


;undefined data 

WORD 

O 

o 


LOG 

Code# 

;code segment 

UndCode:: 


;undefined code 

XOR 

AL,AL 

;zero AL & flags 

RET 


;return 


Thus, it is always safe to load or call an 
external name, whether or not it is present 
at TLINK time. It is bad form to store into 
an undefined external name, however1 
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Memory Allocation A common memory management module MEMMGR 

provides dynamic allocation and deallocation 
of memory space required for disk and message 
buffers, print queues, file and record locks, 
do-file nesting, and so forth. TurboDOS 
reserves a region of memory for such dynamic 
workspace, located immediately above the 
TurboDOS resident. The length of this area 
(in paragraphs) is determined by the patch- 
able parameter OSMLEN. Memory segments are 
allocateddownwardfrom the top of the 
reserved region. Deallocated segments are 
concatenated with any neighbors and threaded 
on a free-memory list. A best-fit algorithm 
is used to reduce memory fragmentation. 

Allocation and deallocation requests are 
coded in this manner: 


;code to allocate a memory segment 


MOV BX,=:36 
CALL ALLOC# 
TEST AL,AL 
JNZ ERROR 
PUSH BX 

;code to deallocate a 
POP BX 
CALL DEALOC# 


;BX=segment size 
;allocate segment 
yalloc successful? 
;NZ -> not enuf mem 
;else, BX=&segment 

memory segment 
;BX=&segment 
;deallocate segment 


ALLOC# prefixes each allocated segment with a 
word containing the segment length, so that 
DEALOC# can tell how much memory is to be 
deallocated. ALLOC# does not zero the newly- 
allocated segment. 
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List Processing 


TurboDOS 


maintains its 
with 


dynamic 


m 4 S n 

ujLUXJ.c:w«>ux'crAiGi.x 


structures as 

1 nnlfarrAC!. 


This technique permits a node to be added or 
deleted anywhere in a list without searching. 
The list head and each list node have a two- 
word linkage (forward and backward pointers). 


List manipulation is coded in this manner; 



LOC 

Data# 

;data segment 

;list 

head (linkage initialized empty) 

LSTHED 

: WORD 

LSTHED 

;forward pointer 


WORD 

LSTHED 

;backward pointer 

;list 

node (linkage not 

initialized) 

LSTNOD 

: WORD 

0 

;forward pointer 


WORD 

0 

;backward pointer 


RES 

128 

;contents of node 


LOC 

Code# 

;program segment 

;code 

to add 

node to end of list 


MOV 

BX,&LSTHED ;BX=&head 


MOV 

DX,&LSTNOD ;DX= &node 


CALL 

LNKEND# 

;link to list end 


;code to unlink node from list 

MOV BX,&LSTNOD ;BX=&node 
CALL UNLINK# ;uniink node 

;code to add node to beginning of list 
MOV BX,&LSTHED ;BX=&head 
MOV DX,&LSTNOD ;DX=&node 
CALL LNKBEG# ;link to list beg. 
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Task Dispatching TurboDOS incorporates a flexible, efficient 

mechanism for dispatching the 8086-family CPU 
among various competing processes. In coding 
drivers for TurboDOS, you must take extreme 
care to use the dispatcher correctly in order 
to attain maximum system performance. 

The dispatcher allows one process to wait for 
some event (for example, data-available or 
seek-complete) while allowing other processes 
to use the processor. For each such event, 
you must define a three-word structure called 
a "semaphore". 

A semaphore consists of a count-word followed 
by a two-word list head. The count-word is 
used by the dispatcher to keep track of the 
status of the event. (At present, only the 
LSB of the count word is used, supporting 
counts in the range -128 to +127.) The list 
head anchors a threaded list of processes 
waiting for the event to occur. 

Two primitive operations operate on a sema¬ 
phore: waiting for the event to occur 
(WAIT#), and signalling that the event has 
occurred (SIGNAL#). They are coded in this 
following manner: 


;this semaphore represents some event 
EVENT: WORD 0 ;semaphore count 

WORD EVENT+2 ;semaphore f-ptr 
WORD EVENT+2 ;semaphore b-ptr 

;wait for the event to occur 

MOV BX,&EVENT ;BX=&semaphore 
CALL WAIT# ;wait for event 

;signal that event has occurred 

MOV BX,&EVENT ;BX=&sempahore 
CALL SIGNAL# ;signal event 
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Task Dispatching Whenever a process waits on a semaphore, 
(Continued} WAIT# decrements the semaphore's count-word. 

Thus, a negative count -N signifies that 
there are N processes waiting for the event 
to occur. Whenever an event is signalled, 
SIGNAL# increments the semaphore count-word 
and awakens the process that has been waiting 
longest. 

If an event is signalled but no process is 
waiting for it, then SIGNAL# increments the 
count-word to a positive value. Thus, a 
positive count N signifies that there have 
been N occurrences of the event for which no 
process was waiting. In this case, the next 
N calls to WAIT# on that semaphore will 
return immediately without waiting. 

Sometimes it is necessary for a process to 
wait for a specific time interval (for exam¬ 
ple, a motor-start delay or carriage-return 
delay) rather than for a specific event. 
TurboDOS provides a delay facility (DELAY#) 
that permits other processes to use the CPU 
while one process is waiting for such a timed 
delay. Delay intervals are specified as some 
number of "ticks". A tick is an implementa¬ 
tion-defined interval, usually 1/50 or 1/60 
of a second. Delays are coded thus: 


; delay for one-tenth of a second 

MOV BX,=6 ;BX=delay in ticks 

CALL DELAY# ;delay process 


Accuracy of delays is usually plus-or-minus 
one tick. A delay of zero ticks may be 
specified to relinquish the processor to 
other processes on a "courtesy" basis. 

All driver delays should be accomplished via 
WAIT# or DELAY#, never by spinning in a loop. 
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Interrupt Service Dispatching is especially efficient when used 

with interrupt-driven devices. Usually, the 
interrupt service routine just calls SIGNAL# 
to signal the interrupt-associated event. 

Most interrupt service routines should exit 
via the usual IRET instruction. However, 
some periodic interrupt (usually a 50 or 60 
hertz clock interrupt) should have an inter¬ 
rupt service routine that exits by jumping to 
the dispatcher entrypoint ISRXIT# to provide 
periodic time-slicing of processes. To avoid 
excessive dispatcher overhead, don't use 
ISRXIT# more than about 60 times per second. 

Before calling any TurboDOS support routine 
(such as SIGNAL#) or referencing any DS- 
relative data, an interrupt service routine 
must call the subroutine GETSDS# to set up 
register DS. 

A simple interrupt service routine might be 
coded like this: 


1 DEVISR: 

POSH 

AX 

save registers 



PUSH 

BX 

n n 



PUSH 

CX 

N II 



PUSH 

DX 

n n 



PUSH 

DS 

n II 



CALL 

GETSDS# 

get system DS 



MOV 

BX,&EVENT 

;BX=&semaphore 



CALL 

SIGNAL# 

signal event 



MOV 

DX,&EOIR 

DX=&end-of-int 



MOV 

AX,=INTN 

AX=interrupt# 



OUT 

DX,AX 

reset interrupt 



POP 

DS 

restore registers 



POP 

DX 

H n 



POP 

CX 

M H 



POP 

BX 

n n 



POP 

AX 

n n 



IRET 


return from int. 
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Poll Routines Devices incapable of interrupting the CPU 

have to be polled by the driver. The dis¬ 
patcher maintains a threaded list of poll 
routines, and executes them every dispatch. 
The function of each poll routine is to check 
the status of its device, and to signal the 
occurrence of some event (for example, data- 
available) when it occurs. The routine 
LNKPOL# links a poll routine onto the poll 
list, and UNLINK# removes it. 

A poll routine must be coded so that it will 
not signal the occurrence of a particular 
event more than once. The best way to assure 
this is for the poll routine to unlink itself 
from the poll list as soon as it has signal¬ 
led the event. An example: 


EVENT: WORD 0 ;semaphore 

WORD EVENT+2 
WORD EVENT+2 

;driver waits for event 

MOV DX,&POLNOD ;DX=&poll node 
CALL LNKPOL# ;activate poll rtn 
CALL POLRTN ;optional pretest 
MOV BX,&EVENT ;BX=&semaphore 
CALL WAIT# ;wait for event 


;poll routine signals event when detected 


POLNOD: WORD 0 
WORD 0 


poll rtn linkage 

n n II 


POLRTN: IN 

AL,=STAT 

;AL=device status 

TEST 

AL,=MASK 

;did event occur? 

JZ 

_X 

;if not, exit 

MOV 

BX,&EVENT 

;BX=&semaphore 

CALL 

SIGNAL# 

;signal event 

MOV 

BX,&POLNOD ;BX=&poll node 

CALL 

UNLINK# 

;unlink poll rtn 

_X: RET 


;all done 
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Mutual Exclusion TurboDOS is fully re-entrant at the process 

and kernel levels. However/ most driver 
modules are not coded re-entrantly (since 
most peripheral devices can only do one thing 
at a time). Consequently/ most drivers must 
make use of a mutual-exclusion interlock to 
prevent TurboDOS from invoking them re-ent- 
rantly. 

This is very easy to accomplish using the 
basic semaphore mechanism of the dispatcher. 
It is only necessary to define a semaphore 
with its count-word initialized to 1 (instead 
of 0). Mutual exclusion may then be accom¬ 
plished by calling WAIT# upon entry and 
SIGNAL# upon exit. An example: 


;mutual-exclusion semaphore 


MXSPH: WORD 

1 

;count-word=lI 

WORD 

MXSPH+2 


WORD 

MXSPH+2 

• 

DRIVER: MOV 

BX/&MXSPH 

;BX=&semaphore 

CALL 

• 

• 

WAIT# 

;wait if in-use 

• 

• 

MOV 

BX/&MXSPH 

;BX=&semaphore 

CALL 

SIGNAL# 

;unlock mut-excl 

RET 


7 done 
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Sample Driver Here is a simple device driver for an inter- 

Using Interrupts rupt-driven serial input device. It illus¬ 
trates coding techniques discussed so far: 



MXSPH: 

WORD 

1 

MX semaphore 




WORD 

MXSPH+2 





WORD 

MXSPH+2 




RDASPH: 

WORD 

0 

RDA semaphore 




WORD 

RDASPH+2 





WORD 

RDASPH+2 




CHRSAV: 

BYTE 

0 ; 

saved input char 



;device 

driver main code 



INPDRV: 

;MOV 

BX,&MXSPH 

;BX= &MXsemaphor e 




CALL 

WAIT# j 

lock MX 




STI 

« 

1 

need ints enabled 




MOV 

BX,&RDASPH ;BX=&semaphore 




CALL 

WAIT# ; 

wait data avail 




PUSH 

CHRSAV ; 

stack input char 




MOV 

BX,&MXSPH 

;BX=&MXsemaphore 




CALL 

SIGNAL# ;unlock MX 




POP 

AX ;return AL=char 




RET 

« 

1 

done 



;interrupt service routine 



INPISR: 

;PUSH 

AX 

save registers 




PUSH 

BX 

n n 




PUSH 

CX 

If n 




PUSH 

DX 

n II 




PUSH 

DS 

n II 




CALL 

GETSDS# 

get system DS 




IN 

AL,=INPUT 

;get input char 




MOV 

CHRSAV,AL 

;save for driver 




MOV 

BX,&RDASPH ;BX=&semaphore 




CALL 

SIGNAL# 

signal data avail 




POP 

DS 

restore registers 




POP 

DX 

If n 




POP 

CX 

n n 




POP 

BX 

II n 




POP 

AX 

■ II 




IRET 


return from int. 



4-9 






TurboDOS 1.4 8086 CODING CONVENTIONS 

Implementor's Guide 

Sample Driver 
Using Polling 


Copyright 1984 by Software 2000, Inc. 
All rights reserved. 


Sample Driver 
Using Polling 


Here is a simple device driver for non-inter¬ 
rupting serial input device. It illustrates 


how polling is 

used: 


1 

1 

MXSPH: 

WORD 

1 

;MX semaphore 

1 


WORD 

MXSPH+2 


1 


WORD 

MXSPH+2 


1 

RDASPH: 

WORD 

0 

;RDA semaphore 

1 


WORD 

RDASPH+2 




WORD 

RDASPH+2 


1 

1 

CHRSAV: 

BYTE 

0 

; saved input char 

1 

1 

;device 

driver main code 

1 

INPDRV: 

;MOV 

BX,&MXSPH 

;BX=&MXsemaphore 

1 


CALL 

WAIT# 

;lock MX 

1 


MOV 

DX,&POLNOD ;DX=&pollnode 

1 


CALL 

LNKPOL# 

;activate poll rtn 

1 


CALL 

POLRTN 

;optional pretest 

1 


MOV 

BX,&RDASPH ;BX=&semaphore 

1 


CALL 

WAIT# 

;wait data avail 

1 


PUSH 

CHRSAV 

;stack input char 

1 


MOV 

BX,&MXSPH 

;BX=&MXsemaph 

1 


CALL 

SIGNAL# 

;unlock MX 

1 


POP 

AX 

;return AL=char 

1 

1 


RET 


;done 

1 

1 

;device 

poll 

routine with linkage 

I 

POLNOD: 

WORD 

0 

;poll rtn linkage 

1 


WORD 

0 


1 

POLRTN: 

IN 

AL,=STAT 

;get device status 

1 


TEST 

AL,=MASK 

;data available? 

1 


JZ 

_X 

;if not, exit 

1 


IN 

AL,=DATA 

;get input char 

I 


MOV 

CHRSAV,AL 

;save for driver 

1 


MOV 

BX,&RDASPH ;BX=&semaphore 

1 


CALL 

SIGNAL# 

;signal data avail 

1 


MOV 

BX,&POLNOD ;BX=&pollnode 

I 


CALL 

UNLINK# 

;unlink poll rtn 

1 

_^X: 

RET 


;done 
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Inter-Process 

Messages 


To pass messages from one process to another, 
a five—word structure called a "message node" 
is used. A message node consists of a three- 
word semaphore followed by a two-word message 
list head. Routines are provided for sending 
messages to a message node (SNDMSG#), and 
receiving messages from a message node 
(RCVMSG#). Typically, the sending process 
allocates a memory segment in which to build 
the message, and the receiving process deal¬ 
locates the segment after reading the mes¬ 
sage. The first two words of each message 
must be reserved for a list-processing link¬ 
age. Coding is done in this manner: 


;message node 


MSGNOD: WORD 

0 

;semaphore part 

WORD 

MSGNOD+2 

,11 n 

1 

WORD 

MSGNOD+2 

,11 n 

r 

WORD 

MSGNOD+6 

;message list head 

WORD 

MSGNOD+6 

f 

;one process 

allocates/builds/sends msg 

MOV 

BX,=12+4 

;BX=message size+4 

CALL 

ALLOC# 

;allocate segment 

PUSH 

BX 

;save &segment 

• 

• 


;build msg in seg 

POP 

DX 

;DX=&segment 

MOV 

BX,&MSGNOD ;BX=&msgnode 

CALL 

SNDMSG# 

;send message 

;Other process reads/deallocates message 

MOV 

BX,&MSGNOD ;BX=&msgnode 

CALL 

RCVMSG# 

;receive message 

PUSH 

BX 

;save &segment 

• 


;process message 

POP 

BX 

;BX=&segment 

CALL 

DEALOC# 

;deallocate seg 
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Console Routines TurboDOS includes several handy console I/O 

subroutines which may be called from within 
driver modules as illustrated: 


;raw console I/O routines 

CALL CONST# ;get status in AL 
TEST AL,AL ;input char avail? 

JZ X ;if not, exit 

CALL CONIN# ;get input in AL 

CALL UPRCAS# ;make upper-case 
MOV CL,AL ;char to CL 

CALL CONOUT# ;output char in CL 

;message output routines 
;message must be null-terminated 

CALL DMS# ;output following 
MSG: BYTE "This is a test messageXO" 

MOV BX,&MSG ;BX=:&message 
CALL DMSBX# ;output msg *BX 

;binary-to-decimal output routine 

MOV BX,=31416 ;BX=word value 

CALL DECOUT# ;displays decimal 


Sign-On Message You may add your own custom sign-on message 

to TurboDOS. Your message will be displayed 
at cold-start immediately following the nor¬ 
mal TurboDOS sign-on and copyright notice. 

Your sign-on message must be coded as an 
ASCII character string terminated with a $ 
delimiter, and labelled with the public entry 
symbol USRSOM. An example: 


USRSOM::BYTE OxOD, OxOA 

BYTE "Implementation by " 
byte "Trigon Computer Corp." 
BYTE "$" 
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Resident Process You can code a resident process that runs in 

the background concurrent with other system 
activities, and link it into TurboDOS. The 
create-process subroutine CRPROC# may be 
called to create such a process at cold-start 
as shown: 


HDWNIT: 

:MOV 

BX,=128 

;BX=workspace size 


CALL 

ALLOC# 

;alloc workspace 
;BX=&workspace 


MOV 

DX,&MYPROC ;DX=&entrypoint 


CALL 

• 

• 

CRPROC# 

;create process 

MYPROC: 

INC 

COUNT[DI] 

;increment count 


MOV 

DX,=60*60 

;ticks/minute 


MOV 

CL,=2 

;T-function 2 


CALL 

OTNTRY# 

;delay 1 minute 


JMP 

MYPROC 

;loop forever 


CRPROC# automatically allocates a TurboDOS 
process area (address appears in register SI) 
and a stack area (address appears in SP). If 
the process requires a re-entrant workspace, 
it should be allocated with ALLOC# and passed 
to CRPROC# in BX (as shown above), and will 
appear to the new process in register DI. 

The resident process must make all operating 
system requests by calling OCNTRY# or OTNTRY# 
with a C-function or T-function number in 
register CL. It must not execute INT OxEO or 
INT OxDF, nor make direct calls on kernel 
routines such as WAIT#, SIGNAL#, DELAY#, 
SNDMSG#, RCVMSG#, ALLOC#, and DEALOC#. 
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Resident Process A resident process is not attached to a con- 
(Continued) sole, so any console I/O requests will be 

ignored. 

You can do file processing within a resident 
process, using the normal C-functions open, 
close, read, write, and so forth, called via 
OCNTRY#. First, however, you must remember 
to warm-start with C-function 0 (OCNTRY#), 
and then log-on with T-function 14 (OTNTRY#). 

A resident process must always be coded to 
preserve the contents of index register SI, 
which Turbodos relies upon as a pointer to 
its process area. The process may use all 
other registers as desired. 


User-Defined The User-Defined Function (T-function 41) 
Function provides a means of adding your own special 

functions to the normal TurboDOS repertoire 
of C-functions and T-functions. To do this, 
you simply create a function processor sub¬ 
routine with the public entrypoint symbol 
USRFCN. 

Whenever a program invokes T-function 41, 
TurboDOS transfers control to your USRFCN 
routine. On entry, ES:CX contains the 
address of the 128-byte record area passed 
from the caller's current DMA address, and 
registers BX and DX contain whatever values 
the caller loaded into them. Your USRFCN 
routine may return data to the caller in the 
128-byte record area (address in CX at entry) 
and in any of the registers AL-BX-CX-DX. 

Architecturally, your USRFCN routine is in¬ 
side the TurboDOS kernel. Consequently, it 
may call kernel subroutines directly. Any 
calls to C-functions and T-functions must 
therefore be made by means of two special 
recursive entrypoints; XCNTRY# and XTNTRYt. 
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DRIVER INTERFACE 


This section explains how to code hardware- 

Lve 

specifications 


uepeilUi^iilL. oevx^e ULiVcrj. uiuuuj.c;o/ emu k/j. e:s>e;*ic.o 


formal interface 
category of driver required by 


for each 
TurboDOS. 


Following this section is a large appendix 
that contains assembler source listings of 
actual driver modules. The sample drivers 
cover a wide range of peripheral devices, and 
provide an excellent starting point for your 
driver development work. 


General Notes Drivers modules are coded with standard pub¬ 

lic entrypoint names, and linked to TurboDOS 
using the TLINK command. You may package 
your drivers into as many or few separate 
modules as you like. In general, it is 
easier to reconfigure TurboDOS for a variety 
of devices if the driver for each device is 
packaged as a separate module. 

TurboDOS is designed to accomodate multiple 
disk, console, printer, and network drivers. 
For disk drivers, for instance, the DSKAST is 
normally set up to refer to disk driver 
entrypoints DSKDRA#, DSKDRB#, DSKDRC#, and so 
forth. Each disk driver should be coded with 
the public entrypoint DSKDR^, TLINK automa¬ 
tically maps successive definitions of such 
names by replacing the trailing _ by A, B, C, 
etc. The same technique may be used for 
console, printer, and network driver entry- 
points. 

You must code driver routines to preserve CS, 
DS, SS, SP, SI and DI registers, but you may 
use other registers as desired. 
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Initialization Hardware initialization and interrupt vector 

set-up should be performed in an initializa¬ 
tion routine labelled with the public entry 
symbol HDWNIT:;. TurboDOS calls this routine 
during cold-start with interrupts disabled. 

Your HDWNIT:: routine must not enable inter¬ 
rupts or make calls to WAIT# or DELAY#. In 
most cases, HDWNIT:: will contain a series of 
calls to individual driver initialization 
subroutines contained in other modules. 


Memory Table All 8086 TurboDOS systems must include a 

table that specifies the size and layout of 
main memory. The table must be labelled with 
the public symbol MEMTBL. It must begin with 
a byte value that specifies the number of 
discontiguous regions of main memory (up to 
eight), followed by two words for each region 
which specify the base address and length of 
the segment (both in paragraphs). The first 
segment in the table must be large enough to 
contain the resident portion of 8086 TurboDOS 
plus the dynamic workspace (given by OSMLEN). 

The following example illustrates the simple 
case of a system with 256K of contiguous 
memory starting at zero: 


MODULE 

"MEMTBL" 


LOG 

Data# 

MEMTBL: 

• 

• 



BYTE 

1 


WORD 

0x40 


WORD 

END 

0x4000- 


;module ident 
;data segment 
;memory spec table 
;just one region 
;base (paragraph) 
0x40 ;length (para) 


Note that the first 0x40 paragraphs (IK 
bytes) are reserved for 8086 interrupt 
vectors and must not be included in MEMTBL. 


5-2 







TurboDOS 1.4 8086 
Implementor's Guide 


DRIVER INTERFACE 


Console Driver 


Copyright 1984 by Software 2000/ Inc. 
All rights reserved. 


Console Driver A console driver should be labelled with the 

public entry symbol CONDiL.. A console number 
lifrom CONAST) is passed in register CH. The 
driver must perform a console I/O operation 
according to the operation code passed in 
register DL: 


1 ^ ^ J ^ ^ ^ ^ ^ ^ tiP D- ^ 

I 0 Return status in AL/ char in CL 

I 1 Return input character in AL 

I 2 Output character passed in CL 
I 8 Enter error-message mode 

I 9 Exit error-message mode 

I 10 Conditional output char in CL 


If DL=0/ the driver determines if a console 
input character is available. If no char¬ 
acter is available, the driver returns AL=0. 
If an input character is available, the 
driver returns AL=-1 and the input character 
in CL, D&t loonMRm&l 

TurboDOS depends upon this look-ahead capa¬ 
bility to detect attention requests. The 
driver must not dispatch (via WAIT# or 
DELAY#) when processing a DL=0 call. 

If DL=1, the driver returns an input char¬ 
acter in AL (waiting if necessary). 

If DL=2, the driver displays the output char¬ 
acter passed in CL (waiting if necessary). 

If DL=8, the driver prepares to display a 
TurboDOS error message; if DL=9, it reverts 
to normal. TurboDOS always precedes each 
error message with an DL=8 call and follows 
it with an DL=9 call. This gives the driver 
an opportunity to take special action (25th 
line, reverse video, etc.) for error 
messages. For simple consoles, the driver 
should output CR-LF in response to DL=8 or 9. 
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Console Driver If DL=10/ the driver determines whether or 
(Continued) not it can accept a console output character 

without dispatching (via WAIT# or DELAY#). 
If SO/ it outputs the character passed in CL/ 
and returns AL=-1 to indicate that the char¬ 
acter was accepted. However/ if the driver 
cannot accept a console output character 
without dispatching/ it returns AL=0 to 
indicate that the character was not accepted; 
TurboDOS will then make an DL=2 call to 
output the same character. This special 
conditional output call is used by TurboDOS 
to optimize console output speed by avoiding 
certain dispatch-related overhead whenever 
possible. 

You should make a special effort to code the 
console driver to execute the minimum number 
of instructions possible/ especially func¬ 
tions 0/ 2/ and 10. Excessive use of subrou¬ 
tine callS/ stack operations/ and other time- 
consuming coding techniques can make the 
difference between running the console device 
at full rated speed or something less. Study 
the sample driver listings in the appendix 
with this in mind. 
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Printer Driver A printer driver should be labelled with the 

public entry symbol LStDR_. A printer number 
"(from PTRAST) "is passed in register CH. The 
driver must perform a printer output opera¬ 
tion according to the operation code passed 
in register DL: 


i ,, DL=, , J__ , , , PUDgJ: ion , .^ 

I 

I 2 Print character passed in CL 
I 7 Perform end-of-print-job action 


If DL=2, the driver prints the output charac¬ 
ter passed in CL (waiting if necessary). 

If DL=7, the driver takes any appropriate 
end-of-print-job action. This is quite 
hardware-dependent, and may include slewing 
to top-of-form, homing the print head, 
dropping the ribbon, and so forth. 
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A disk driver should be labelled with the 
public entry symbol DSKDIL.. The driver per¬ 
forms the physical disk operation specified 
by the Physical Disk Request (PDR) packet 
whose address is passed by TurboDOS in index 
register SI. The structure of the PDR packet 
is: 


Offset ] 




;physical 


0[SI3 

BYTE 

KSI] 

BYTE 

2[SI] 

WORD 

4[SI1 

WORD 

61SI] 

WORD 

8[SI] 

WORD 

lOtSIl 

WORD 

12[SI] 

WORD 

14[SI] 

WORD 

;copy 

of disk 

16[SI] 

BYTE 

17ESI] 

WORD 

19ESI] 

BYTE 

20ESI] 

BYTE 

21ESI] 

WORD 

23ESI] 

WORD 

25ESI] 

WORD 


(PDR) packet 
operation code 
drive (base 0) 
track (base 0) 
sector (base 0) 
tsectors to rd/wr 
♦bytes to rd/wr 
DMA offs to rd/wr 
DMA base to rd/wr 
DST address 
specification table (DST) 
BLKSIZ ;block size (3-7) 
;#blocks on disk 
;#directory blocks 
jsector size (0-7) 
;sectors per track 
;tracks on disk 
;reserved tracks 


disk request 
OPCODE 
DRIVE 
TRACK 
SECTOR 
SECCNT 
BYTCNT 
DMAOFF 
DMABAS 
DSTADR 


NMBLKS 

NMBDIR 

SECSIZ 

SECTRK 

TRKDSK 

RESTRK 


The operation to be performed by the driver 
is specified in the first byte of the PDR 
packet (OPCODE) as follows: 




0 Read sectors from disk 

1 Write sectors to disk 

2 Determine disk type, return DST 

3 Determine if drive is ready 

4 Format track on disk 
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If OPCODE=Or the driver reads SE^CNT physical 
sectors (or equivalently. BYTCNt bytes) into 
DMAOFF/DMABAS, Starting at TRACK and SECTOR 
on DRIVE. The driver returns AL=0 if the 
operation is successful, or AL=-1 if an 
unrecoverable error occurs. TurboDOS may 
request multiple consecutive sectors to be 
read, but will never request an operation 
that extends past the end of the track. 

If OPCODE=l, the driver writes SECCNT physi¬ 
cal sectors (or BYTCNT bytes) from 
DMAOFF/DMABAS, starting at TRACK and SECTOR 
on DRIVE. The driver returns AL=0 if the 
operation is successful, or AL=-1 if an 
unrecoverable error occurs. TurboDOS may 
request multiple consecutive sectors to be 
written, but will never request an operation 
that extends past the end of the track. 

If OPCODE=2, the driver must determine the 
type of disk mounted in DRIVE, and must 
return, in the DSTADR field of the PDR 
packet, the address of an 11—byte disk speci¬ 
fication table (DST) structured as follows: 


Offset:, J, . . . . 

0 block size (3=1K,4=2K,...,7=16K) 

1-2 total number of blocks on disk 

3 number of directory blocks 

4 sector size (0=128,...,7=16K) 

5-6 number of sectors per track 

7-8 number of tracks on the disk 
9-10 number of reserved (boot) tracks 


The first byte of the DST (BLKSIZ) specifies 
the allocation block size in bits 2-0. In 
addition, bit 7 is set if the disk is fixed 
(non-removable), and bit 6 is set if file 
extents are limited to 16K (EXM=0). 
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The driver returns AL=-1 if the operation is 
successful, or AL=0 if the drive is not ready 
or the disk type is unrecognizable. On suc¬ 
cessful return, TurboDOS moves a copy of the 
DST into 161SI] through 26ESI], where it is 
available for subsequent operations. 

If OPCODE=3, the driver determines whether 
DRIVE is ready, and returns AL=-1 if it is 
ready or AL=0 if not. 

If OPCODE=4, the driver formats (initializes) 
TRACK on DRIVE, using hardware-dependent 
formatting information at DMAOFF/DMABAS (put 
there by the FORMAT command). The driver 
returns AL=0 if successful, or AL=-1 if an 
unrecoverable error occurs. 
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Network Driver A network circuit driver should be labelled 

with the public entry symbol CKTDR_. A mes¬ 
sage buffer address is passed in register DX. 
The driver must either send or receive a 
network message, according to the operation 
code passed in register CL: 


0 Receive message into buffer at DX 
1 Send message from buffer at DX 


If CL=0, the driver receives a network mes¬ 
sage into the message buffer whose address is 
passed in DX (waiting if necessary). If a 
message is received successfully, the driver 
returns AL=0. If an unrecoverable malfunc¬ 
tion of any remote processor is detected, the 
driver returns AL=-1 with the network address 
of the crashed processor in DX. 

If CL=1, the driver sends a network message 
from the message buffer whose address is 
passed in DX. If the message is sent suc¬ 
cessfully, the driver returns AL=0. If the 
message could not be sent because of an unre¬ 
coverable malfunction of the destination 
processor, the driver returns AL=-1 with the 
network address of the crashed processor in 
DX. 

The structure of a network message buffer is 
shown on the next page. The first two words 
of the buffer are reserved for a linkage used 
by TurboDOS, and should be ignored by the 
driver. The 11-byte message header and 
variable-length message body should be sent 
or received over the circuit. The driver 
needs to look at only the first two header 
fields (MSGLEN and MSGDID) and possibly the 
last field (MSGFCD). 
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Network Driver 
(Continued) 



• 

9 

message buffer format 




WORD 

7 

• 

/•linkage (ignored) 




WORD 

? 

, n n 

/ 



• 

11-byte message header 




BYTE 

MSGLEN 

;msg length 




WORD 

MSGDID 

;destination addr 




BYTE 

MSGPID 

;process id 




WORD 

MSGSID 

/source addr 




WORD 

MSGOID 

/originator addr 




BYTE 

MSGOPR 

/orig'r process id 




BYTE 

MSGLVL 

/forwarding level 




BYTE 

MSGFCD 

/msg format code 



• 

9 

variable-length body 





RES 

7 

/registers 




RES 

1 

/user # and flags 




RES 

37 

/optional FCB data 




RES 

128 

/optional record 



The message format code field MSGFCD contains 
bit-encoded flags that define the format and 
context of each network message. This field 
may be ignored by most simple drivers, but 
its contents may be useful in complex network 
environments. Encoding of MSGFCD is: 


BJwL J.., __ 

0 first message of session 

1 last message of session 

2 continuation message follows 

3 request includes FCB data 

4 request includes record data 

5 reply includes FCB data 

6 reply includes record data 

7 this is a reply message 
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Network Driver 

(Continued) 


The length field MSGLEN represents the number 

A r\ m^coartA *1 *1 

lU ^ Cl^ f .&1A Wju W1V4 Jbix^ W.XX^ Xi^WlVA^J. 

and body (but excluding the linkage). On a 
receive request (CL=0), TurboDOS presets 
MSGLEN to the maximum allowable message 
length, and expects MSGLEN to contain the 
actual message length on return. On a send 
request (CL^l), TurboDOS presets MSGLEN to 
the actual length of the message to be sent. 

In a master/slave network, it is often desir¬ 
able for the circuit driver in the master to 
periodically "poll" the slave processors on 
the circuit to detect any slave malfunctions 
quickly and to effect recovery. If the 
driver reports that a slave has crashed (by 
returning AL=-1 and DX=network-address), then 
the circuit driver must not accept any fur¬ 
ther messages from that slave until TurboDOS 
has completed its recovery process. 

TurboDOS signals the driver that such recov¬ 
ery is complete by sending a dummy message 
destined for the slave in question with a 
length of zero. The driver should not actu¬ 
ally send such a message to the slave, but 
could initiate whatever action is appropriate 
to reset the slave and download a new copy of 
the slave operating system. 

A slave must request an operating system 
download by sending a special download re¬ 
quest message to the master (usually done by 
a bootstrap routine). The download request 
message consists of a standard ll-byte header 
(with MSGPID, MSGOID and MSGFCD zeroed) fol¬ 
lowed by a 1-byte body containing a "download 
suffix" character. The master processor 
addressed by MSGDID will return a reply mes¬ 
sage whose 128-byte body is the first record 
of the download file OSSLAVEx.SYS (where "x" 
is the specified download suffix). 


5-11 




TurboDOS 1.4 8086 
Implementor's Guide 


DRIVER INTERFACE 


Network Driver 
(Continued) 


Copyright 1984 by Software 2000, Inc. 
All rights reserved. 


Network Driver The slave continues to send download request 
(Continued) messages and to receive successive download 

records until it receives a short reply mes¬ 
sage (1-byte body) signifying end-of-file. 
The single byte passed as the body of the 
final short message identifies the system 
disk, and should be passed to the system in 
register AL. 

The entire failure detection, failure recov¬ 
ery, and slave downloading procedure is very 
hardware-dependent. Study the driver listing 
in the appendix for guidance. 
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The comm driver supports the TurboDOS commu¬ 
nications extensions (T-functions 34-40), and 
may be omitted if these functions are not 
used. The driver should be labelled with the 
public entry symbol COMDRV. A comm channel 
number is passed in register CH. The driver 
must perform an I/O operation according to 
the operation code passed in register DLs 


, J,. ^ .^^ F^ns^tlon - 

0 Return input status in AL 

1 Return input character in AL 

2 Output character passed in CL 

3 Set channel baud rate from CL 

4 Return channel baud rate in AL 

5 Set modem controls from CL 

6 Return modem status in AL 


If DL=0, the driver determines if an input 
character is available. If one is available, 
the driver returns AL=-1, otherwise AL=0. 

If DL=1, the driver returns an input char¬ 
acter in AL (waiting if necessary). 

If DL=2, the driver outputs the character 
passed in CL. 

If DL=3, the driver sets the channel baud 
rate according to the baud-rate code passed 
in CL. If DL=4, the driver returns the 
channel baud-rate code in AL. See T-func- 
tions 37 and 38 in the M33. 

for baud-rate code definitions. 

If DL=5, the driver sets the modem controls 
according to the bit-vector passed in CL. If 
DL=6, the driver returns the modem status 
vector in AL. See T-functions 39 and 40 in 
the QJ033. G-UJ-d£ for bit-vector 
definitions. 
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The real-time clock driver does not take the 
form of a subroutine called by TurboDOS, as 
do the other drivers described in this sec¬ 
tion. Rather, the clock driver generally 
consists of an interrupt service routine 
which responds to interrupts from a periodic 
interrupt source (preferably 50 to 60 times a 
second). The interrupt service routine 
should call DLYTIC# once per system tick (to 
synchronize DELAY# requests). It should also 
call RTCSEC# once per second (that is, every 
50 to 60 ticks) to update the system time and 
date. Finally, it should exit by jumping to 
ISRXIT# to provide a periodic dispatcher 
time-slice. Excluding initialization code, a 
typical clock driver might be coded thus; 



RTCCNT; 

BYTE 

60 

divide-by-60 cntr 



RTCISR; 

PUSH 

AX 

save registers 




PUSH 

BX 

n n 




PUSH 

CX 

n H 




PUSH 

DX 

n n 




PUSH 

DS 

n n 




CALL 

GETSDS# 

get system DS 




CALL 

DLYTIC# 

signal one tick 




DEC 

RTCCNT 

decrement counter 




JNZ 


not 60 ticks yet 




MOV 

RTCCNT,=60 ;reset counter 




CALL 

RTCSEC# 

signal one second 



X: 

MOV 

DX,&EOIR 

DX=&end-of-int 




MOV 

AX,=INTN 

AX=interrupt# 




OUT 

DX,AX 

reset interrupt 




POP 

DS 

restore registers 




POP 

DX 

n It 




POP 

CX 

n It 




POP 

BX 

n n 




POP 

AX 

If n 




JMP 

ISRXIT# 

go to dispatcher 
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Clock Driver 

W AAAVi/ 


If the hardware is capable of determining the 


\JLCL uc: CLiiUi 


fVsrr 

Vk/jr 


TTI ifN ^ C! 

uicaAxih7 


of a battery-powered clock, for example), the 
clock driver may initialize the following 
public symbols in the RTCMGR module: 


SECS: : 

BYTE 

0 

;seconds 

0-59 

MINS:: 

BYTE 

0 

;minutes 

0-59 

HOURS:: 

BYTE 

0 

;hours 

0-24 

JDATE:: 

WORD 

0x8001 

?Julian 

date 


;base 31-Dec-47 
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The bootstrap is usually contained in a ROM 
or on a boot track. Its function is to 
search all disk drives for the TurboDOS 
loader program OSLOAD.CMD, and to load and 
execute it if found. To generate a boot¬ 
strap, use TLINK to combine the standard 
bootstrap module OSBOOT.O with your own 
hardware-dependent driver. Your driver must 
define the following public names: INIT, 
SELECT, READ, XFER, CODE, and DATA. 

INIT:: is called once to perform any required 
hardware initialization. It returns with 
register AX set to the paragraph address of 
the load base (where the file OSLOAD.CMD 
should be loaded into memory by the boot¬ 
strap). This address should be chosen so 
that OSLOAD will not overlay the bootstrap or 
the operating system to be loaded. 

SELECT:: is called to select the disk drive 
passed in AL (0-15). If the selected drive 
is not ready or non-existent, it returns 
AL=0. Otherwise, it returns AL=-1 and the 
address of an 11-byte disk specification 
table (DST) in register SI (see page 5-7). 

READ:: is called to read one physical sector 
from the last-selected drive. The track is 
passed in CX, the sector in DX, the DMA 
offset in BX, and the DMA base in ES. It 
must return AL=0 if successful, or AL=-1 if 
an unrecoverable error occurred. 

XFER:: is transferred to at the end of the 
bootstrap process. In most cases, this 
routine must set register DS to the base 
paragraph address of the loader (normally the 
load base returned by INIT:: plus 8 to allow 
for the .CMD header), set location DS:0080 to 
zero (to simulate a null command tail), and 
jump to the loader (using a JMPF to set CS=DS 
and IP=0xl00). 
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Bootstrap 

(Continued) 


CODE;: defines the base paragraph (CS value) 
under which the bootstrap itself is to be 
executed. OSBOOT loads this value into 
register CS before calling INIT::/ SELECT:;/ 
READ:: or XFERzu 


DATA:: defines the base paragraph (DS value) 
of a 128“byte RAM area that OSBOOT may use 
for working storage. (It should not be 
located where OSLOAD.CMD will be loadedl) 
OSBOOT loads this value into register DS 
before calling INIT::/ SELECT;;/ READ:: or 
XFER::. 
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(Intentionally left blank.) 
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OTOASH Command Some TurboDOS implementations require that a 

Z80 master processor download 8086-family 
slave processors. In writing the network 
circuit driver for the Z80 master processor, 
it is often necessary to embed a download 
bootstrap routine written in 8086 code. The 
utility program OTOASM.CMD is designed to 
simplify this process. 

OTOASM converts an 8086 object file (type .0) 
produced by TASM into a Z80 source file (type 
.ASM) acceptable to either the PASM or M80 
assemblers. The output file contains a 
sequence of data definition statements (.BYTE 
and .WORD, or DB and DW) representing 8086 
machine-language. 


Syntax I 

I OTOASM filename {-M} 


Explanation The "filename" argument must not have an 

explicit type, and specifies the name of both 
the input file "filename.0" and the output 
file "filename.ASM" to be used. The "-M" 
option causes the output to be formatted for 
the M80 assembler rather than the PASM assem¬ 
bler . 

The input file (type .0) must not contain any 
relocatable tokens. Consequently, the 8086 
source module (type ,A) must define only 
absolute location counter values (LOC) and 
must make no external references (# suffix). 
Public symbols may be defined as long as they 
do not have relocatable values. 
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SAMPLE DRIVER 
SOURCE LISTINGS 


The remainder of this document consists of 
assembler source listings of actual drivers. 
The listings comprise the drivers for a 
working TurboDOS system for the IBM Personal 
Computer with 256K of RAM. 


The listings appear in the following order: 


L Module^ 


[ DREQUATE 
I MPBIPC 
I NITIPC 
I CONIPC 
I LSTPPA 
I LSTACA 
I RTCIPC 
I DSKIPC 
I MSTIPC 


common symbolic equates 
IBM PC bootstrap driver 
IBM PC driver initialization 
IBM PC TTY-mode console driver 
IBM PC parallel printer driver 
IBM PC serial printer driver 
IBM PC real-time clock driver 
IBM PC floppy disk driver 
IBM PC memory spec table (256K) 


1 


Network circuit drivers will be furnished in 
the next edition of this document. In the 
meantime/ refer to the Z&Q. 

Guide for circuit driver examples. 


B-1 



Note: 


TurboDOS 1.4 8086 
Implementor's Guide 


Copyright 1984 by Software 2000, 
All rights reserved. 


Saiiple source listings are available upon request. 


(Intentionally left blank. 


SAMPLE pi^xVER 
SOURCE LISTINGS 


Inc. 
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